A class to send messages to a target BLooper or BHandler. More...

Public Member Functions
	BMessenger ()
	Creates an uninitialized BMessenger.

	BMessenger (const BHandler handler, const BLooper looper=NULL, status_t *result=NULL)
	Creates a BMessenger and initializes it to target the local BHandler and/or BLooper.

	BMessenger (const BMessenger &other)
	Creates a BMessenger and initializes it to have the same target as the supplied messenger.

	BMessenger (const char signature, team_id team=-1, status_t result=NULL)
	Creates a BMessenger and initializes it to target the already running application identified by its signature and/or team ID.

	~BMessenger ()
	Frees all resources associated with this object.

uint32	HashValue () const
	Returns a hash value that uniquely identifies the messenger.

bool	IsValid () const
	Returns whether the messenger's target looper still exists.

team_id	Team () const
	Returns the ID of the team that the messenger's target belongs to.

Target
bool	IsTargetLocal () const
	Returns whether the messenger and target belong to the same team.

BHandler *	Target (BLooper **looper) const
	Returns the handler and looper targeted by the messenger (if the target is local).

bool	LockTarget () const
	Locks the BLooper targeted by the messenger (if the target is local).

status_t	LockTargetWithTimeout (bigtime_t timeout) const
	Locks the BLooper targeted by the messenger with a timeout (if the target is local).

SendMessage
status_t	SendMessage (uint32 command, BHandler *replyTo=NULL) const
	Delivers a BMessage with command `what` identifier to the messenger's target. A response may be sent to the replyTo handler asynchronously.

status_t	SendMessage (BMessage message, BHandler replyTo=NULL, bigtime_t timeout=B_INFINITE_TIMEOUT) const
	Delivers a message to the messenger's target. A response message may be sent back to the replyTo handler asynchronously.

status_t	SendMessage (BMessage *message, BMessenger replyTo, bigtime_t timeout=B_INFINITE_TIMEOUT) const
	Delivers a message to the messenger's target. A response message may be sent back to the replyTo messenger's target asynchronously.

status_t	SendMessage (uint32 command, BMessage *reply) const
	Delivers a BMessage with command `what` identifier to the messenger's target and waits for a reply BMessage synchronously.

status_t	SendMessage (BMessage message, BMessage reply, bigtime_t deliveryTimeout=B_INFINITE_TIMEOUT, bigtime_t replyTimeout=B_INFINITE_TIMEOUT) const
	Delivers a message to the messenger's target and waits for a reply to come back synchronously.

SetTo
status_t	SetTo (const char *signature, team_id team=-1)
	Reinitializes a BMessenger to target the already running application identified by the supplied signature and/or team ID.

status_t	SetTo (const BHandler handler, const BLooper looper=NULL)
	Reinitializes a BMessenger to target the local BHandler and/or BLooper.

Operators
BMessenger &	operator= (const BMessenger &other)
	Assignment operator, makes this BMessenger a copy of other.

bool	operator== (const BMessenger &other) const
	Comparison operator, returns whether this and other have the same target.

Detailed Description

A class to send messages to a target BLooper or BHandler.

A BMessenger can send messages to local and remote targets. If the target belongs to the same team as the BMessenger it is a local target, otherwise if the target lives in a separate address space it is a remote target.

The most significant (set of) method(s) in the class is SendMessage(), which sends its message to the target. For a local target SendMessage() is roughly equivalent in terms of efficiency to posting a message directly to the messenger's target (i.e. BLooper::PostMessage()).

If you supply a target BMessenger or BHandler to SendMessage() the method will return immediately after delivery and the response will be handled asynchronously, otherwise the method will return once the reply has been delivered or after a set timeout.

The global be_app_messenger pointer targets the main message loop of be_app is automatically initialized for you when you create a BApplication object, you can use it wherever a BMessenger is called for.

Since: BeOS R3

Constructor & Destructor Documentation

◆ BMessenger() [1/4]

BMessenger::BMessenger ( )

Creates an uninitialized BMessenger.

Since: BeOS R3

◆ BMessenger() [2/4]

BMessenger::BMessenger	(	const char *	signature,
		team_id	team = `-1`,
		status_t *	result = `NULL`
	)

Creates a BMessenger and initializes it to target the already running application identified by its signature and/or team ID.

When only a signature is given, and multiple instances of the application are running it is indeterminate which one is chosen as the target. In case only a team ID is passed, the target application is identified uniquely. If both are supplied, the application identified by the team ID must have a matching signature, otherwise the initialization fails.

Parameters

signature	The target application's signature. May be `NULL`.
team	The target application's team ID. May be < 0.
result	An optional pointer to a pre-allocated status_t into which the result of the initialization is written.

Since: BeOS R3

◆ BMessenger() [3/4]

BMessenger::BMessenger	(	const BHandler *	handler,
		const BLooper *	looper = `NULL`,
		status_t *	_result = `NULL`
	)

Creates a BMessenger and initializes it to target the local BHandler and/or BLooper.

When a NULL handler is supplied, the preferred handler in the looper is targeted. If no looper is supplied the looper that handler belongs to is used instead – that means in particular, that the handler must already belong to a looper. If both are supplied the handler must belong to the looper.

Parameters

handler	The target handler. May be `NULL`.
looper	The target looper. May be `NULL`.
_result	An optional pointer to a pre-allocated status_t into which the result of the initialization is written.

Since: BeOS R3

◆ BMessenger() [4/4]

BMessenger::BMessenger ( const BMessenger & other )

Creates a BMessenger and initializes it to have the same target as the supplied messenger.

Since: BeOS R3

◆ ~BMessenger()

BMessenger::~BMessenger ( )

Frees all resources associated with this object.

Since: BeOS R3

Member Function Documentation

◆ HashValue()

uint32 BMessenger::HashValue ( ) const

Returns a hash value that uniquely identifies the messenger.

Since: Haiku R1

◆ IsTargetLocal()

bool BMessenger::IsTargetLocal ( ) const

Returns whether the messenger and target belong to the same team.

Returns: true if the messenger is properly initialized and its target belong ot the same team, false if they reside in separate address spaces.

Since: BeOS R3

◆ IsValid()

bool BMessenger::IsValid ( ) const

Returns whether the messenger's target looper still exists.

Warning: This method does not check whether the target handler also still exists.

Returns: true, if the messenger's target looper still exists, false otherwise.

Since: BeOS R3

◆ LockTarget()

bool BMessenger::LockTarget ( ) const

Locks the BLooper targeted by the messenger (if the target is local).

This method is a shorthand for retrieving the targeted looper via Target() and calling BLooper::Lock() on the looper afterwards.

See also: BLooper::Lock() for details.

Returns: true, if the looper was locked successfully, false, if the messenger was not properly initialized, the target was remote, or the targeted looper was invalid.

Since: BeOS R3

◆ LockTargetWithTimeout()

status_t BMessenger::LockTargetWithTimeout ( bigtime_t timeout ) const

Locks the BLooper targeted by the messenger with a timeout (if the target is local).

This method is a shorthand for retrieving the targeted looper via Target() and calling BLooper::LockWithTimeout() on the looper afterwards.

See also: BLooper::LockWithTimeout() for details.

Returns: A status code, B_OK on success or an error code otherwise, all other error codes returned by BLooper::LockWithTimeout().

Return values

B_OK	if the looper could be locked successfully,
B_BAD_VALUE	if the messenger is not properly initialized, the target is remote, or the targeted looper is invalid.

See also: BLooper::LockWithTimeout() for more error codes.

Since: BeOS R3

◆ operator=()

BMessenger & BMessenger::operator= ( const BMessenger & other )

Assignment operator, makes this BMessenger a copy of other.

Parameters

other the messenger to be copied.

Returns: A reference to this object.

Since: BeOS R3

◆ operator==()

bool BMessenger::operator== ( const BMessenger & other ) const

Comparison operator, returns whether this and other have the same target.

Parameters

other The messenger to be compared to.

Returns: true, if the messengers have the same target or if both aren't properly initialized, false otherwise.

Since: BeOS R3

◆ SendMessage() [1/5]

status_t BMessenger::SendMessage	(	BMessage *	message,
		BHandler *	replyTo = `NULL`,
		bigtime_t	timeout = `B_INFINITE_TIMEOUT`
	)		const

Delivers a message to the messenger's target. A response message may be sent back to the replyTo handler asynchronously.

A copy of the supplied message is sent and the caller retains ownership of message.

If the target's message port is full, the method waits until space becomes available in the port or the specified timeout occurs (whichever happens first). After delivery the method returns immediately. It does not wait until the target processes the message or even sends a reply.

This method does not return by default until the message has been delivered. You can set a delivery timeout in microseconds.

Parameters

message	The message to be sent.
replyTo	The handler for a response message to be sent. May be `NULL`.
timeout	The message delivery timeout in microseconds. (optional)

Returns: A status code, B_OK on success or an error code otherwise.

Return values

B_OK	Everything went fine.
B_BAD_PORT_ID	The messenger was not properly initialized or its target didn't exist.
B_WOULD_BLOCK	A delivery timeout of 0 was supplied and the target port was full when trying to deliver the message.
B_TIMED_OUT	The timeout expired while trying to deliver the message.

Since: BeOS R3

◆ SendMessage() [2/5]

status_t BMessenger::SendMessage	(	BMessage *	message,
		BMessage *	reply,
		bigtime_t	deliveryTimeout = `B_INFINITE_TIMEOUT`,
		bigtime_t	replyTimeout = `B_INFINITE_TIMEOUT`
	)		const

Delivers a message to the messenger's target and waits for a reply to come back synchronously.

A copy of the supplied message is sent and the caller retains ownership of message.

The method does wait for a reply. The reply message is copied into reply. If the target doesn't send a reply or if a reply timeout occurs, the what field of reply is set to B_NO_REPLY.

This method does not return by default until the message has been delivered and the reply has come back. You can set a deliveryTimeout and a replyTimeout in microseconds.

Parameters

message	The message to be sent.
reply	A pointer to a pre-allocated BMessage which the reply message will be copied into.
deliveryTimeout	The message delivery timeout in microseconds. (optional)
replyTimeout	The reply message timeout in microseconds. (optional)

Returns: A status code, B_OK on success or an error code otherwise.

Return values

B_OK	Everything went fine.
B_BAD_PORT_ID	The messenger was not properly initialized or its target didn't exist.
B_WOULD_BLOCK	A delivery timeout of 0 was supplied and the target port was full when trying to deliver the message.
B_TIMED_OUT	The timeout expired while trying to deliver the message.
B_NO_MORE_PORTS	All reply ports were in use.

Since: BeOS R3

◆ SendMessage() [3/5]

status_t BMessenger::SendMessage	(	BMessage *	message,
		BMessenger	replyTo,
		bigtime_t	timeout = `B_INFINITE_TIMEOUT`
	)		const

Delivers a message to the messenger's target. A response message may be sent back to the replyTo messenger's target asynchronously.

A copy of the supplied message is sent and the caller retains ownership of message.

If the target's message port is full, the method waits until space becomes available in the port or the specified timeout occurs (whichever happens first). After delivery the method returns immediately. It does not wait until the target processes the message or even sends a reply.

This method does not return by default until the message has been delivered. You can set a delivery timeout in microseconds.

Parameters

message	The message to be sent.
replyTo	A messenger specifying the target for a response message.
timeout	The message delivery timeout in microseconds. (optional)

Returns: A status code, B_OK on success or an error code otherwise.

Return values

B_OK	Everything went fine.
B_BAD_PORT_ID	The messenger was not properly initialized or its target didn't exist.
B_WOULD_BLOCK	A delivery timeout of 0 was supplied and the target port was full when trying to deliver the message.
B_TIMED_OUT	The timeout expired while trying to deliver the message.

Since: BeOS R4

◆ SendMessage() [4/5]

status_t BMessenger::SendMessage	(	uint32	command,
		BHandler *	replyTo = `NULL`
	)		const

Delivers a BMessage with command what identifier to the messenger's target. A response may be sent to the replyTo handler asynchronously.

If the target's message port is full, the method waits indefinitely, until space becomes available in the port. After delivery the method returns immediately. It does not wait until the target processes the message or even sends a reply.

Parameters

command	The what field of the message to deliver.
replyTo	The handler to which a reply to the message shall be sent. May be `NULL`.

Returns: A status code, B_OK on success or an error code otherwise.

Return values

B_OK	Everything went fine.
B_BAD_PORT_ID	The messenger is not properly initialized or its target doesn't exist anymore.

Since: BeOS R3

◆ SendMessage() [5/5]

status_t BMessenger::SendMessage	(	uint32	command,
		BMessage *	reply
	)		const

Delivers a BMessage with command what identifier to the messenger's target and waits for a reply BMessage synchronously.

The method does wait for a reply. The reply message is copied into reply. If the target doesn't send a reply, the what field of reply is set to B_NO_REPLY.

Parameters

command	The what field of the message to deliver.
reply	A pointer to a pre-allocated BMessage object which the reply message will be copied into.

Returns: A status code, B_OK on success or an error code otherwise.

Return values

B_OK	Everything went fine.
B_BAD_PORT_ID	The messenger was not properly initialized or its target didn't exist.
B_NO_MORE_PORTS	All reply ports were in use.

Since: BeOS R3

◆ SetTo() [1/2]

status_t BMessenger::SetTo	(	const BHandler *	handler,
		const BLooper *	looper = `NULL`
	)

Reinitializes a BMessenger to target the local BHandler and/or BLooper.

When a NULL handler is supplied, the preferred handler in the given looper is targeted. If no looper is supplied the looper the given handler belongs to is used – that means in particular, that the handler must already belong to a looper. If both are supplied the handler must actually belong to looper.

Parameters

handler	The target handler. May be `NULL`.
looper	The target looper. May be `NULL`.

Returns: A status code, B_OK if the reinitialization was successful or an error code otherwise.

Return values

B_OK	The reinitialization was successful.
B_BAD_VALUE	Both handler and looper were `NULL` or invalid.
B_MISMATCHED_VALUES	The looper of the supplied handler and looper didn't match.

Since: Haiku R1

◆ SetTo() [2/2]

status_t BMessenger::SetTo	(	const char *	signature,
		team_id	team = `-1`
	)

Reinitializes a BMessenger to target the already running application identified by the supplied signature and/or team ID.

When only a signature is given, and multiple instances of the application are running it is indeterminate which one is chosen as the target. In case only a team ID is passed, the target application is identified uniquely. If both are supplied, the application identified by the team ID must have a matching signature, otherwise the initialization fails.

Parameters

signature	The target application's signature. May be `NULL`.
team	The target application's team ID. May be negative.

Returns: A status code, B_OK if the reinitialization was successful or an error code otherwise.

Return values

B_OK	The reinitialization was successful.
B_BAD_VALUE	No application with the given signature or team ID was running.
B_BAD_TYPE	No team ID was given and the signature was `NULL`.
B_MISMATCHED_VALUES	The supplied signature and the signature of the team didn't match.

Since: Haiku R1

◆ Target()

BHandler * BMessenger::Target ( BLooper ** _looper ) const

Returns the handler and looper targeted by the messenger (if the target is local).

The handler is returned directly, the looper by reference. If both are NULL, the object is either not properly initialized, the target objects have been deleted or the target is remote. If only the returned handler is NULL, either the looper's preferred handler is targeted or the handler has been deleted.

Parameters

_looper A pointer to a pre-allocated BLooper pointer into which the pointer to the targeted looper is written.

Returns: The BHandler targeted by the messenger.

Since: BeOS R3

◆ Team()

team_id BMessenger::Team ( ) const

Returns the ID of the team that the messenger's target belongs to.

Returns: The team of the messenger's target.

Since: BeOS R3

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BMessenger() [1/4]

◆ BMessenger() [2/4]

◆ BMessenger() [3/4]

◆ BMessenger() [4/4]

◆ ~BMessenger()

Member Function Documentation

◆ HashValue()

◆ IsTargetLocal()

◆ IsValid()

◆ LockTarget()

◆ LockTargetWithTimeout()

◆ operator=()

◆ operator==()

◆ SendMessage() [1/5]

◆ SendMessage() [2/5]

◆ SendMessage() [3/5]

◆ SendMessage() [4/5]

◆ SendMessage() [5/5]

◆ SetTo() [1/2]

◆ SetTo() [2/2]

◆ Target()

◆ Team()