Public Member Functions | Static Public Member Functions | List of all members
BMessageRunner Class Reference

Provides a mechanism for sending one or more messages to a messenger at a specified interval and receive reply messages. More...

Public Member Functions

 BMessageRunner (BMessenger target, const BMessage *message, bigtime_t interval, int32 count=-1)
 Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds, reply messages are sent to be_app_messenger. More...
 
 BMessageRunner (BMessenger target, const BMessage &message, bigtime_t interval, int32 count=-1)
 Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds, reply messages are sent to be_app_messenger. More...
 
 BMessageRunner (BMessenger target, const BMessage *message, bigtime_t interval, int32 count, BMessenger replyTo)
 Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds. More...
 
 BMessageRunner (BMessenger target, const BMessage &message, bigtime_t interval, int32 count, BMessenger replyTo)
 Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds. More...
 
virtual ~BMessageRunner ()
 Frees all resources associated with the object. More...
 
status_t GetInfo (bigtime_t *interval, int32 *count) const
 Returns the time interval between two messages and the number of times the message has still to be sent. More...
 
status_t InitCheck () const
 Returns the initialization status. More...
 
status_t SetCount (int32 count)
 Sets the number of times message should be sent. More...
 
status_t SetInterval (bigtime_t interval)
 Sets the interval of time between messages. More...
 

Static Public Member Functions

static status_t StartSending (BMessenger target, const BMessage *message, bigtime_t interval, int32 count)
 Creates and initializes a detached BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds, reply messages are sent to be_app_messenger. More...
 
static status_t StartSending (BMessenger target, const BMessage *message, bigtime_t interval, int32 count, BMessenger replyTo)
 Creates and initializes a detached BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds. More...
 

Detailed Description

Provides a mechanism for sending one or more messages to a messenger at a specified interval and receive reply messages.

The application that creates the BMessageRunner can specify the message, the BMessenger to send the message to, how often to send the message, how many times to send the message, and the BMessenger to send reply messages from.

The system roster handles dispatching the messages to the appropriate messengers at the specified time intervals. The target for any reply messages is be_app_messenger by default, or it can be specified in the constructor.

After initializing a BMessageRunner, the initialization can and should be checked by calling InitCheck(). BMessageRunner will not take ownership of the message, you may freely change or delete the message after initialization.

The BMessageRunner can be reconfigured (to change the interval or count) by calling SetInterval() and SetCount(). This is useful if you want to stop a BMessageRunner from sending messages early or if messages are set to be sent forever.

Since
BeOS R5

Constructor & Destructor Documentation

◆ BMessageRunner() [1/4]

BMessageRunner::BMessageRunner ( BMessenger  target,
const BMessage message,
bigtime_t  interval,
int32  count = -1 
)

Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds, reply messages are sent to be_app_messenger.

Parameters
targetThe target of the message(s).
messageThe message to be sent to the target.
intervalPeriod of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.
countSpecifies how many times the message shall be sent. A negative value indicates that the message will be sent forever, or until the BMessageRunner is reconfigured or deleted.
Since
BeOS R5

◆ BMessageRunner() [2/4]

BMessageRunner::BMessageRunner ( BMessenger  target,
const BMessage message,
bigtime_t  interval,
int32  count = -1 
)

Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds, reply messages are sent to be_app_messenger.

Parameters
targetTarget of the message(s).
messageThe message to be sent to the target.
intervalPeriod of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.
countSpecifies how many times the message shall be sent. A negative value indicates that the message will be sent forever, or until the BMessageRunner is reconfigured or deleted.
Since
Haiku R1

◆ BMessageRunner() [3/4]

BMessageRunner::BMessageRunner ( BMessenger  target,
const BMessage message,
bigtime_t  interval,
int32  count,
BMessenger  replyTo 
)

Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds.

This constructor also allows you to specify the target for replies to the delivered messages.

Parameters
targetTarget of the message(s).
messageThe message to be sent to the target.
intervalPeriod of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.
countSpecifies how many times the message shall be sent. A negative value indicates that the message will be sent forever, or until the BMessageRunner is reconfigured or deleted.
replyToTarget replies to the delivered message(s) shall be sent to.
Since
BeOS R5

◆ BMessageRunner() [4/4]

BMessageRunner::BMessageRunner ( BMessenger  target,
const BMessage message,
bigtime_t  interval,
int32  count,
BMessenger  replyTo 
)

Creates and initializes a new BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds.

This constructor also allows you to specify the target for replies to the delivered messages.

Parameters
targetTarget of the message(s).
messageThe message to be sent to the target.
intervalPeriod of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.
countSpecifies how many times the message shall be sent. A negative value indicates that the message will be sent forever, or until the BMessageRunner is reconfigured or deleted.
replyToTarget replies to the delivered message(s) shall be sent to.
Since
Haiku R1

◆ ~BMessageRunner()

BMessageRunner::~BMessageRunner ( )
virtual

Frees all resources associated with the object.

Since
BeOS R5

Member Function Documentation

◆ GetInfo()

status_t BMessageRunner::GetInfo ( bigtime_t interval,
int32 *  count 
) const

Returns the time interval between two messages and the number of times the message has still to be sent.

Both parameters (interval and count) may be NULL.

Parameters
intervalPointer to a pre-allocated bigtime_t variable to be set to the time interval. May be NULL.
countPointer to a pre-allocated int32 variable to be set to the number of times the message has still to 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_VALUEinterval was 0 or negative, or the message runner had already sent all messages and became unusable.
Since
BeOS R5

◆ InitCheck()

status_t BMessageRunner::InitCheck ( ) const

Returns the initialization status.

Note
As soon as the last message is sent, the message runner becomes unusable. InitCheck() will still return B_OK, but SetInterval(), SetCount() and GetInfo() will all fail.
Returns
B_OK if the object was properly initialized or an error code otherwise.
Since
BeOS R5

◆ SetCount()

status_t BMessageRunner::SetCount ( int32  count)

Sets the number of times message should be sent.

Parameters
countSpecifies how many times the message shall be sent. A negative value indicates that the message will be sent forever, or until the BMessageRunner is reconfigured or deleted.
Returns
A status code, B_OK on success or an error code otherwise.
Return values
B_OKEverything went fine.
B_NO_INITThe message runner was not properly initialized.
B_BAD_VALUEinterval was 0 or negative, or the message runner had already sent all messages and became unusable.
Since
BeOS R5

◆ SetInterval()

status_t BMessageRunner::SetInterval ( bigtime_t  interval)

Sets the interval of time between messages.

Parameters
intervalThe new interval in microseconds.
Returns
A status code, B_OK on success or an error code otherwise.
Return values
B_OKEverything went fine.
B_NO_INITThe message runner was not properly initialized.
B_BAD_VALUEinterval was 0 or negative, or the message runner had already sent all messages and became unusable.
Since
BeOS R5

◆ StartSending() [1/2]

status_t BMessageRunner::StartSending ( BMessenger  target,
const BMessage message,
bigtime_t  interval,
int32  count 
)
static

Creates and initializes a detached BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds, reply messages are sent to be_app_messenger.

You cannot alter the runner after the creation, and it will be deleted automatically the last message is sent.

Parameters
targetTarget of the message(s).
messageThe message to be sent to the target.
intervalPeriod of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.
countSpecifies how many times the message shall be sent. A negative value indicates that the message will be sent forever, or until the BMessageRunner is reconfigured or deleted.
Since
Haiku R1

◆ StartSending() [2/2]

status_t BMessageRunner::StartSending ( BMessenger  target,
const BMessage message,
bigtime_t  interval,
int32  count,
BMessenger  replyTo 
)
static

Creates and initializes a detached BMessageRunner and instructs the system roster to send the specified message to the target count times every interval microseconds.

You cannot alter the runner after the creation, and it will be deleted automatically once the last message is sent.

Parameters
targetTarget of the message(s).
messageThe message to be sent to the target.
intervalPeriod of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.
countSpecifies how many times the message shall be sent. A negative value indicates that the message will be sent forever, or until the BMessageRunner is reconfigured or deleted.
replyToTarget replies to the delivered message(s) shall be sent to.
Since
Haiku R1