os::Messenger Class Reference

Public Member Functions
	Messenger ()
	Default constructor. More...
	Messenger (const Handler *pcHandler, const Looper *pcLooper=NULL)
	Construct a messenger targeting a looper and optionally a specific handler. More...
	Messenger (const Messenger &cMessenger)
	Copy contructor. More...
	Messenger (port_id hPort)
	Construct a messenger from a loopers message port. More...
	Messenger (const char *pzPort)
	Construct a messenger for a named message port. More...
	~Messenger ()
	Destructor. More...
Handler *	GetTarget (Looper **ppcLooper) const
	Get a pointer to the handler targeted by this handler. More...
bool	IsTargetLocal (void) const
	Check if the targeted handler/looper lives in the calling process. More...
bool	IsValid (void) const
	Check if the messenger is fully initialized. More...
status_t	LockTarget (void) const
	Lock the destination looper. More...
status_t	SendMessage (Message *pcMessage, Message *pcReply, bigtime_t nSendTimeOut=INFINITE_TIMEOUT, bigtime_t nReplyTimeOut=INFINITE_TIMEOUT) const
	Deliver a message syncronously. More...
status_t	SendMessage (Message *pcMessage, Handler *pcReplyHandler=NULL, bigtime_t nTimeOut=INFINITE_TIMEOUT) const
	Deliver message asyncronously. More...
status_t	SendMessage (int nCode, Message *pcReply=NULL) const
	Short for SendMessage( &Message( nCode ), pcReply ) More...
status_t	SendMessage (int nCode, Handler *pcReplyHandler) const
	Short for SendMessage( &Message( nCode ), pcReplyHandler ) More...
Messenger &	operator= (const Messenger &cMessenger)
	Copy the target from another messenger. More...
bool	operator== (const Messenger &cMessenger) const
	Compare two messengers. More...

Friends
class	Message
class	::SrvWidget
class	::SrvWindow
class	::SrvApplication
class	::SrvEvents
class	NodeMonitor
class	Event

Detailed Description

Description:

See Also

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Constructor & Destructor Documentation

Messenger::Messenger

(

)

Description:

Initialize the messenger to a known but invalid state. The messenger must be further initialized before it can be used to send messages.

See Also

Looper, Message

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Messenger::Messenger	(	const Handler *	pcHandler,
		const Looper *	pcLooper = NULL
	)

Description:

A messenger can target a Looper or specific Handler inside a Looper. If pcHandler is NULL the messenger will not have a specific target. Messages will be sendt to pcLooper and it will be dispatched to the currently default Handler in that looper. If the looper don't have a default handler the message will be handled by the loopers own HandleMessage() member.

If pcHandler is non-NULL the message will always be sent directly to this handler independent of which handler is active. In this case the target looper will be the looper pcHandler is a member of and the pcLooper parameter should be NULL. This means that only a handler that is added to a looper already can be targeted by a messenger.

Parameters

pcHandler	If non-NULL this specify the handler that will receive messages sendt by this messenger. The handler must already be added to a Looper with os::Looper::AddHandler().
pcLooper	If pcHandler is NULL this parameter must point to valid os::Looper object. The looper will then receive the messages sendt and it will be dispatched to the current default handler or handled by the looper itself if there is no default handler.

See Also

os::Looper, os::Message

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Handler::GetLooper(), and os::Looper::GetMsgPort().

Messenger::Messenger

(

const Messenger &

cMessenger

)

Description:

Copy contructor

Parameters

cMessenger

The messenger to copy.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Messenger::Messenger

(

port_id

hPort

)

Description:

This constructor is mostly intended for internal usage by the toolkit but are made available to applications. It will construct a messenger that send messages to a specific message port. This should primarily be a message port belonging to an os::Looper. This can be useful to establish communication between mostly unrelated processes since unlike os::Looper and os::Handler pointers the message port ID can be passed between processes without being invalidated.

Note

It is not possible to target a specific os::Handler using this constructor. You should normally use the constructor taking a os::Looper or os::Handler pointer rather than this.

Parameters

hPort

The message port this messanger should send messages through. This will primarily come from os::Looper::GetMsgPort().

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Messenger::Messenger

(

const char *

pzPort

)

Description:

This constructor is used to target named message ports (public message ports), and can be used for communication between processes.

Note

Use IsValid() to check whether the message port was found.

Parameters

pzPort

The name of the message port this messenger should send messages through.

Author

Henrik Isaksson (henri.nosp@m.k@is.nosp@m.aksso.nosp@m.n.tk)

Messenger::~Messenger

(

)

Description:

Does nothing.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Member Function Documentation

Handler * Messenger::GetTarget

(

Looper **

ppcLooper

)

const

Description:

Return a pointer to the os::Handler targeted by this messenger. If no specific handler is targeted the targeted looper will be returned.

If the messenger is not fully initialized, it's target have been deleted or the target is in a remote process this member will return NULL.

Warning:

Since each looper run their own thread and might terminate themself at any moment it is very important that you never try to call any member on any of the returned objects before the looper is properly locked. Unless you have some other mechanism that guarantee you that the looper will be terminated between the return of this member and your attempt to lock it you must use os::Looper::SafeLock() rather than os::Looper::Lock() and make sure you validate that the looper was successfully locked before any further actions are performed.

Parameters

ppcLooper

If non-NULL a pointer to the looper owning the target will be written here.

Returns

Pointer to the destined os::Handler (this might be a looper if no specific handler is targeted) or NULL if the messenger is invalid or targets a handled/looper in a remote process.

See Also

IsTargetLocal(), LockTarget(), os::Looper::SafeLock()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::Invoker::GetTarget().

bool Messenger::IsTargetLocal

(

void

)

const

Description:

Returns true if the target belongs to this process and false if it lives in a remote process.

See Also

GetTarget(), LockTarget()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::Invoker::IsTargetLocal().

bool Messenger::IsValid

(

void

)

const

Description:

Return true if the messenger have been initialized with a valid target and false if valid target have never been specified.

Note

This member only check if the messenger was properly constructed. It will not check if the target is still valid.

Returns

True if initialized with a valid target false otherwhice.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::Translator::Invoke(), SendMessage(), and os::Invoker::SetTarget().

status_t Messenger::LockTarget

(

void

)

const

Description:

Lock the os::Looper object targeted by this messenger.

Note:

This member only work when the target is local

Returns

If the target was successfully locked 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.

See Also

GetTarget(), IsTargetLocal(), os::Looper::Lock(), os::Looper::SafeLock()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::SafeLock().

Messenger & Messenger::operator=

(

const Messenger &

cMessenger

)

Description:

Copy the target from another messenger.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

bool Messenger::operator==

(

const Messenger &

cMessenger

)

const

Returns true if they target the same handler.

Description:

Compare two messengers. Returns true if they target the same handler.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

status_t Messenger::SendMessage	(	Message *	pcMsg,
		Message *	pcReply,
		bigtime_t	nSendTimeOut = INFINITE_TIMEOUT,
		bigtime_t	nReplyTimeOut = INFINITE_TIMEOUT
	)		const

Description:

Send a message to the target and optionally wait for a reply. If the pcReply argument is non-NULL, this function will not return until we receive a reply from the target or the nReplyTimeOut occure. The messenger will create a temporary message port from which it receives the reply. If pcReply is NULL the member will return as soon as the pcMsg message is delivered.

Bugs:

The timeout values is currently ignored, and is always interpreted as INFINITE_TIMEOUT

Parameters

pcMsg	The message to deliver. The messages will be copyed and the caller keep ownership over the object.
pcReply	The message to fill out with the reply or NULL to skip waiting for a reply.
nSendTimeOut	Time to wait for a free slot in the receiving port before failing with errno == ETIME
nReplyTimeOut	Time to wait for reply before failing with errno == ETIME

Returns

On success 0 is returned. In the case of failure -1 is returned and a error code is written to the global variable errno.

See Also

os::Message::SendReply(), os::Message

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References IsValid().

Referenced by os::RegistrarManager::ClearTypeExtensions(), os::RegistrarManager::ClearTypeHandlers(), os::RegistrarManager::GetAppList(), os::Event::GetLastEventMessage(), os::Event::GetRemoteChildren(), os::Font::GetSupportedCharacters(), os::RegistrarManager::GetType(), os::RegistrarManager::GetTypeAndIcon(), os::RegistrarManager::GetTypeCount(), os::DateView::HandleMessage(), os::CalendarView::HandleMessage(), os::FileRequester::HandleMessage(), os::ColorRequester::HandleMessage(), os::InputBox::HandleMessage(), os_priv::DirKeeper::Idle(), os::Invoker::Invoke(), os::Translator::Invoke(), MoveFileThread(), os::FileRequester::OkToQuit(), os::ColorRequester::OkToQuit(), os::InputBox::OkToQuit(), os::Event::PostEvent(), os::Event::Register(), os::RegistrarManager::RegisterType(), os::RegistrarManager::RegisterTypeExtension(), os::RegistrarManager::RegisterTypeHandler(), os::RegistrarManager::RegisterTypeIcon(), os::RegistrarManager::RegistrarManager(), SendMessage(), os::RegistrarManager::SetDefaultHandler(), os::Font::SetFamilyAndStyle(), os::Event::SetMonitorEnabled(), os::Event::SetToRemote(), os::TreeViewCheckNode::Toggle(), os::CheckRow::Toggle(), UnmountThread(), os::RegistrarManager::UnregisterType(), os::RegistrarManager::UpdateAppList(), os::Event::~Event(), and os::RegistrarManager::~RegistrarManager().

status_t Messenger::SendMessage	(	Message *	pcMsg,
		Handler *	pcReplyHandler = NULL,
		bigtime_t	nTimeOut = INFINITE_TIMEOUT
	)		const

Description:

The message is delivered to the target, and this member returns imediatly. If pcReplyHandler is non-NULL the following reply will be directed to that handler in a asyncronous manner through the Handler's Looper thread.

Bugs:

The timeout value is currently ignored, and is always interpreted as INFINITE_TIMEOUT

Parameters

pcMsg	The message to deliver. The messages will be copyed and the caller keep ownership over the object.
pcReplyHandler	The handler that should handle the reply or NULL if no reply is required.
nTimeOut	Time to wait for a free slot in the receiving port before failing with errno == ETIME

Returns

On success 0 is returned. In the case of failure -1 is returned and a error code is written to the global variable errno.

See Also

os::Message::SendReply(), os::Message

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Handler::GetLooper(), os::Looper::GetMsgPort(), and IsValid().

status_t Messenger::SendMessage	(	int	nCode,
		Message *	pcReply = NULL
	)		const

Description:

Short for SendMessage( &Message( nCode ), pcReply )

See Also

status_t SendMessage( Message*, Message*, bigtime_t, bigtime_t ) const

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References SendMessage().

status_t Messenger::SendMessage	(	int	nCode,
		Handler *	pcReplyHandler
	)		const

Description:

Short for SendMessage( &Message( nCode ), pcReplyHandler )

See Also

status_t SendMessage( Message*, Handler*, bigtime_t ) const

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References SendMessage().

Friends And Related Function Documentation

friend class ::SrvApplication

friend

friend class ::SrvEvents

friend

friend class ::SrvWidget

friend

friend class ::SrvWindow

friend

friend class Event

friend

friend class Message

friend

friend class NodeMonitor

friend