All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions | List of all members
BMessenger Class Reference

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.
 
BHandlerTarget (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
BMessengeroperator= (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
signatureThe target application's signature. May be NULL.
teamThe target application's team ID. May be < 0.
resultAn 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
handlerThe target handler. May be NULL.
looperThe target looper. May be NULL.
_resultAn 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_OKif the looper could be locked successfully,
B_BAD_VALUEif 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
otherthe 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
otherThe 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
messageThe message to be sent.
replyToThe handler for a response message to be sent. May be NULL.
timeoutThe message delivery timeout in microseconds. (optional)
Returns
A status code, B_OK on success or an error code otherwise.
Return values
B_OKEverything went fine.
B_BAD_PORT_IDThe messenger was not properly initialized or its target didn't exist.
B_WOULD_BLOCKA delivery timeout of 0 was supplied and the target port was full when trying to deliver the message.
B_TIMED_OUTThe 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
messageThe message to be sent.
replyA pointer to a pre-allocated BMessage which the reply message will be copied into.
deliveryTimeoutThe message delivery timeout in microseconds. (optional)
replyTimeoutThe reply message timeout in microseconds. (optional)
Returns
A status code, B_OK on success or an error code otherwise.
Return values
B_OKEverything went fine.
B_BAD_PORT_IDThe messenger was not properly initialized or its target didn't exist.
B_WOULD_BLOCKA delivery timeout of 0 was supplied and the target port was full when trying to deliver the message.
B_TIMED_OUTThe timeout expired while trying to deliver the message.
B_NO_MORE_PORTSAll 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
messageThe message to be sent.
replyToA messenger specifying the target for a response message.
timeoutThe message delivery timeout in microseconds. (optional)
Returns
A status code, B_OK on success or an error code otherwise.
Return values
B_OKEverything went fine.
B_BAD_PORT_IDThe messenger was not properly initialized or its target didn't exist.
B_WOULD_BLOCKA delivery timeout of 0 was supplied and the target port was full when trying to deliver the message.
B_TIMED_OUTThe 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
commandThe what field of the message to deliver.
replyToThe 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_OKEverything went fine.
B_BAD_PORT_IDThe 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
commandThe what field of the message to deliver.
replyA 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_OKEverything went fine.
B_BAD_PORT_IDThe messenger was not properly initialized or its target didn't exist.
B_NO_MORE_PORTSAll 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
handlerThe target handler. May be NULL.
looperThe target looper. May be NULL.
Returns
A status code, B_OK if the reinitialization was successful or an error code otherwise.
Return values
B_OKThe reinitialization was successful.
B_BAD_VALUEBoth handler and looper were NULL or invalid.
B_MISMATCHED_VALUESThe 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
signatureThe target application's signature. May be NULL.
teamThe 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_OKThe reinitialization was successful.
B_BAD_VALUENo application with the given signature or team ID was running.
B_BAD_TYPENo team ID was given and the signature was NULL.
B_MISMATCHED_VALUESThe 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
_looperA 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