BInvoker

Derived from: none

Declared in: be/app/Invoker.h

Library: libbe.so

Summary

BInvoker is a convenience class that bundles up everything you need to create a handy message-sending package. The BInvoker contains: (a) a BMessage, (b) a BMessenger (that identifies a target handler), and (c) an optional BHandler that handles replies. You set these ingredients, invoke Invoke(), and off goes the message to the target. Replies are sent to the reply handler (be_app by default).

BInvoker uses BMessenger::SendMessage() to send its messages. The invocation is asynchronous, and there's no time limit on the reply.

BInvoker is mostly used as a mix-in class. A number of classes in the Interface Kit—notably BControl—derive from BInvoker.

Constructor and Destructor

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 aBMessenger 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()

Deletes the object's BMessage.

Member Functions

Command() see SetMessage()

HandlerForReply() see SetHandlerForReply()

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.

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);

IsTargetLocal() see SetTarget()

Message() see SetMessage()

Messenger() see SetTarget()

SetHandlerForReply(), HandlerForReply()

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).—

SetMessage(), Message(), Command()

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.

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

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 app.

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.

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

Target() see SetTarget()