BInvoker¶

Constructor and Destructor¶

BInvoker()

BInvoker::BInvoker(BMessage *message, BMessenger messenger)
BInvoker::BInvoker(BMessage *message, const BHandler *handler, const BLooper *looper = NULL)
BInvoker::BInvoker()

Initializes the BInvoker by setting its message and its messenger.

The object’s BMessage is taken directly as message—the object is not copied. The BInvoker takes over ownership of the BMessage that you pass in.
The object’s BMessenger is copied from messenger, or initialized with looper and handler. See the BMessenger class for details on how a BMessenger identifies a target.

If you want a reply handler, you have to call SetHandlerForReply() after the constructor returns. You can reset the message and messenger through SetMessage() and SetTarget().

~BInvoker()

virtual BInvoker::~BInvoker()

Deletes the object’s BMessage.

Member Functions¶

BeginInvokeNotify(), EndInvokeNotify()

void BInvoker::BeginInvokeNotify(uint32 kind = B_CONTROL_INVOKED)

void BInvoker::EndInvokeNotify()

If for some reason you need to implement a method that emulates an InvokeNotify() call inside an Invoke() implementation, you should wrap the invocation code in these functions. They set up and tear down an InvokeNotify() context.

Invoke(), InvokeNotify()

virtual status_t BInvoker::Invoke(BMessage *message = NULL)

status_t BInvoker::InvokeNotify(BMessage *message, uint32 kind = B_CONTROL_INVOKED)

Invoke() tells the BInvoker’s messenger to send a message. If message is non-NULL, that message is sent, otherwise the object sends its default message (i.e. the BMessage that was passed in the constructor or in SetMessage()). The message is sent asynchronously with no time limit on the reply.

Note

Regarding the use of the default message vs the argument, a common practice is to reserve the default message as a template, and pass a fine-tuned copy to Invoke()

/* Add the current system time to a copy of
   the default message. */
BMessage copy(invoker.Message());
copy.AddInt64("when", system_time());
invoker.Invoke(copy);

The InvokeNotify() function sends the message to the target, using the notification change code specified by kind. If message is NULL, nothing gets sent to the target, but any watchers of the invoker’s handler will receive their expected notifications. By default, the kind is B_CONTROL_INVOKED, the same kind sent by a straight Invoke().

Invoke() doesn’t call SendNotices() by default; you’ll have to implement code to do it yourself. Here’s how:

status_t BControl::Invoke(BMessage* msg) {
   bool notify = false;
   uint32 kind = InvokeKind(notify);

   BMessage clone(kind);
   status_t err = B_BAD_VALUE;

   if (!msg && !notify) {
      // If no message is supplied, pull it from the BInvoker.
      // However, ONLY do so if this is not an InvokeNotify()
      // context -- otherwise, this is not the default invocation
      // message, so we don't want it to get in the way here.
      // For example, a control may call InvokeNotify() with their
      // "modification" message... if that message isn't set,
      // we still want to send notification to any watchers, but
      // -don't- want to send a message through the invoker.
      msg = Message();
   }

   if (!msg) {
      // If not being watched, there is nothing to do.
      if( !IsWatched() ) return err;
   } else {
      clone = *msg;
   }

   clone.AddInt64("when", system_time());
   clone.AddPointer("source", this);
   clone.AddInt32("be:value",fValue);
   clone.AddMessenger(B_NOTIFICATION_SENDER, BMessenger(this));

   if( msg ) err = BInvoker::Invoke(&clone);

   // Also send invocation to any observers of this handler.
   SendNotices(kind, clone);

   return err;
}

Return Code	Description
`B_OK`.	The message was sent.
`B_BAD_VALUE`.	No default message, and no message argument.
Other errors.	Forwarded from `BMessenger::SendMessage()`.

InvokeKind()

uint32 BInvoker::InvokeKind(bool *notify = NULL)

Returns the kind passed to InvokeNotify(). This should be called from within your implementation of Invoke() if you need to determine what kind was specified when InvokeNotify() was called. If you care whether Invoke() or InvokeNotify() was originally called, you can specify a pointer to a bool, notify, which is set to true if InvokeNotify() was called, or false if Invoke() was called. This lets you fetch the InvokeNotify() arguments from your Invoke() code without breaking compatibility with older applications by adding arguments to Invoke().

SetHandlerForReply(), HandlerForReply()

virtual status_t BInvoker::SetHandlerForReply(BHandler *replyHandler)

BHandler *BInvoker::HandlerForReply() const

SetHandlerForReply() sets the BHandler object that handles replies that are sent back by the target. By default (or if replyHandler is NULL), replies are sent to the BApplication object.

HandlerForReply() returns the object set through SetHandlerForReply(). If the reply handler isn’t set, this function returns NULL, it doesn’t return be_app (even though be_app will be handling the reply).

Return Code	Description
`B_OK`	SetHandlerForReply() always returns `B_OK` it doesn’t check for validity.

SetMessage(), Message(), Command()

virtual status_t BInvoker::SetMessage(BMessage *message)

BMessage *BInvoker::Message() const

uint32 BInvoker::Command() const

SetMessage() sets the BInvoker’s default message to point to message (the message is not copied). The previous default message (if any) is deleted; a NULL message deletes the previous message without setting a new one. The BInvoker owns the BMessage that you pass in; you mustn’t delete it yourself.

Message() returns a pointer to the default message, and Command() returns its what data member. Lacking a default message, the functions return NULL.

Return Code	Description
`B_OK`	SetMessage() always returns `B_OK`.

SetTarget(), Target(), IsTargetLocal(), Messenger()

virtual status_t BInvoker::SetTarget(BMessenger messenger)
virtual status_t BInvoker::SetTarget(const BHandler *handler, const BLooper *looper = NULL)

BHandler *BInvoker::Target(BLooper **looper = NULL) const

bool BInvoker::IsTargetLocal() const

BMessenger BInvoker::Messenger() const

These functions set and query the BInvoker’s target. This is the BHandler to which the object sends a message when Invoke() is called. The target is represented by a BMessenger object; you can set the BMessenger as a copy of messenger, or initialize it with looper and handler. See the BMessenger class for details on how a BMessenger identifies a target.

Target() returns the BHandler that’s targeted by the object’s messenger. If looper is non-NULL, the BLooper that owns the BHandler is returned by reference. If the target was set as a looper’s preferred handler (i.e. SetTarget(NULL, looper)), or if the target hasn’t been set yet, Target() returns NULL. The function returns NULL for both objects if the target is remote.

IsTargetLocal() returns true if the target lives within the BInvoker’s application, and false if it belongs to some other application.

Messenger() returns a copy of the BMessenger object the BInvoker uses to send messages. If a target hasn’t been set yet, the return will be invalid.

Return Code	Description
`B_OK`.	The target was successfully set.
`B_BAD_VALUE`.	The proposed handler doesn’t belong to a `BLooper`.
`B_MISMATCHED_VALUES`.	handler doesn’t belong to looper.

Warning

SetTarget() doesn’t detect invalid BLoopers and BMessengers.

SetTimeout(), Timeout()

status_t BInvoker::SetTimeout(bigtime_t timeout)

bigtime_t BInvoker::Timeout() const

SetTimeout() sets the timeout that will be used when sending the invocation message to the invoker’s target. By default this is B_INFINITE_TIMEOUT.

Timeout() returns the current setting for this value.

Return Code	Description
`B_OK`.	No error.