The Be Book The Application Kit The Application Kit Index

BMessenger

Derived from: none
Declared in:  be/app/Messenger.h
Library: libbe.so
Allocation: Stack or constructor
Summary:  more...


A BMessenger represents and sends messages to a message target, where the target is a BLooper and, optionally, a specific BHandler within that looper. The target can live in the same application as the BMessenger (a local target), or it can live in some other application (a remote target).

BMessenger's most significant function is SendMessage(), which sends its argument BMessage to the target.

For a local target, SendMessage() is roughly equivalent, in terms of efficiency, to posting a message directly to the BMessenger's target (i.e BLooper::PostMessage()).

The global be_app_messenger BMessenger pointer, which targets be_app's main message loop, is automatically initialized for you when you create your BApplication object. You can use it wherever BMessengers are called for.


Constructor and Destructor


BMessenger()

BMessenger(const BHandler *handler,
      const BLooper *looper = NULL,
      status_t *error = NULL)
BMessenger(const char *signature,
      team_id team = –1,
      status_t *error = NULL)
BMessenger(const BMessenger &messenger)
BMessenger(void)

Creates a new BMessenger and sets its target to a local looper/handler, to the (running) application identified by signature or team, or to the target of some other messenger.

Messages sent to a remote target are received and handled by the remote application's BApplication object.

The BMessenger doesn't own its target.

RETURN CODES

The constructor places an error code in error (if provided).


~BMessenger()

~BMessenger()

Frees the BMessenger; the target isn't affected.


Member Functions


IsTargetLocal()  see Target()


IsValid()

bool IsValid(void) const

Returns true if the target looper, whether local or remote, still exists.

This function doesn't tell you whether the looper is actually ready to receive messages, or whether the handler (if it was specified in the constructor) exists. In other words, a valid BMessenger is no guarantee that a message will actually get to the target.


LockTarget() , LockTargetWithTimeout()

bool LockTarget(void) const
status_t LockTargetWithTimeout(bigtime_t timeout) const

These functions apply to local targets only.

These functions attempt to lock the target looper in the manner of the similarly named BLooper functions (see BLooper::LockTarget()). In addition to the error codes reported there, these functions return false and B_BAD_VALUE (respectively) if the target isn't local, or if the looper is otherwise invalid.


SendMessage()

status_t SendMessage(BMessage *message,
      BMessage *reply,
      bigtime_t deliveryTimeout = B_INFINITE_TIMEOUT,
      bigtime_t replyTimeout = B_INFINITE_TIMEOUT) const
status_t SendMessage(BMessage *message,
      BHandler *replyHandler = NULL,
      bigtime_t deliveryTimeout = B_INFINITE_TIMEOUT) const
status_t SendMessage(BMessage *message,
      BMessenger *replyMessenger,
      bigtime_t deliveryTimeout = B_INFINITE_TIMEOUT) const
status_t SendMessage(uint32 command, BMessage *reply) const
status_t SendMessage(uint32 command, BHandler *replyHandler = NULL) const

Sends a copy of message (or a BMessage based on a command constant) to the object's target. The caller retains ownership of message. The function doesn't return until the message has been delivered; if you're sending a message (as opposed to a command constant) you can set a microsecond delivery timeout through deliveryTimeout.

The target can respond to the message:

Use caution when requesting a synchronous reply: If you call SendMessage() from the target looper's thread, you'll deadlock (or, at best, time out).

RETURN CODES

If you specified a handler when you constructed your BMessenger, and if that handler has since changed loopers, SendMessage() won't deliver its message, but it doesn't complain (it returns B_OK).


Target() , IsTargetLocal() , Team()

BHandler *Target(BLooper **looper) const
bool IsTargetLocal(void) const
inline team_id Team(void) const

Target() returns the BMessenger's handler (directly) and looper (by reference in looper). This function only works for local targets. If Target() returns NULL, it can mean one of four things:

IsTargetLocal() returns true if the target is local. Team() returns a target's team.


Team()  see Target()


Operators


= (assignment)

BMessenger &operator =(const BMessenger&)

Sets the left-side BMessenger's target to that of the right-side object.


== (equality)

bool operator ==(const BMessenger&) const

Two BMessengers are equal if they have the same target.


The Be Book The Application Kit The Application Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..