Add BMessageRunner docs
This commit is contained in:
John Scipione
@@ -0,0 +1,267 @@
|
||||
/*
|
||||
* Copyright 2001-2015 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* John Scipione, [email protected]
|
||||
* Ingo Weinhold, [email protected]
|
||||
*
|
||||
* Corresponds to:
|
||||
* headers/os/app/MessageRunner.h hrev48689
|
||||
* src/kits/app/MessageRunner.cpp hrev48689
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\file MessageRunner.h
|
||||
\ingroup app
|
||||
\ingroup libbe
|
||||
\brief Provides the BMessageRunner class.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\class BMessageRunner
|
||||
\ingroup app
|
||||
\ingroup libbe
|
||||
\brief 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 \c 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
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMessageRunner::BMessageRunner(BMessenger target,
|
||||
const BMessage* message, bigtime_t interval, int32 count)
|
||||
\brief Creates and initializes a new BMessageRunner and instructs the
|
||||
system roster to send the specified \a message to the \a target
|
||||
\a count times every \a interval microseconds, reply messages are
|
||||
sent to \c be_app_messenger.
|
||||
|
||||
\param target The target of the message(s).
|
||||
\param message The message to be sent to the target.
|
||||
\param interval Period of time before the first message is sent and
|
||||
between messages (if more than one shall be sent) in microseconds.
|
||||
\param count Specifies 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
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMessageRunner::BMessageRunner(BMessenger target,
|
||||
const BMessage& message, bigtime_t interval, int32 count)
|
||||
\brief Creates and initializes a new BMessageRunner and instructs the
|
||||
system roster to send the specified \a message to the \a target
|
||||
\a count times every \a interval microseconds, reply messages are
|
||||
sent to \c be_app_messenger.
|
||||
|
||||
\param target Target of the message(s).
|
||||
\param message The message to be sent to the target.
|
||||
\param interval Period of time before the first message is sent and
|
||||
between messages (if more than one shall be sent) in microseconds.
|
||||
\param count Specifies 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
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMessageRunner::BMessageRunner(BMessenger target,
|
||||
const BMessage* message, bigtime_t interval, int32 count,
|
||||
BMessenger replyTo)
|
||||
\brief Creates and initializes a new BMessageRunner and instructs the
|
||||
system roster to send the specified \a message to the \a target
|
||||
\a count times every \a interval microseconds.
|
||||
|
||||
This constructor also allows you to specify the target for replies to
|
||||
the delivered messages.
|
||||
|
||||
\param target Target of the message(s).
|
||||
\param message The message to be sent to the target.
|
||||
\param interval Period of time before the first message is sent and
|
||||
between messages (if more than one shall be sent) in microseconds.
|
||||
\param count Specifies 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.
|
||||
\param replyTo Target replies to the delivered message(s) shall be sent to.
|
||||
|
||||
\since BeOS R5
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMessageRunner::BMessageRunner(BMessenger target,
|
||||
const BMessage& message, bigtime_t interval, int32 count,
|
||||
BMessenger replyTo)
|
||||
\brief Creates and initializes a new BMessageRunner and instructs the
|
||||
system roster to send the specified \a message to the \a target
|
||||
\a count times every \a interval microseconds.
|
||||
|
||||
This constructor also allows you to specify the target for replies to
|
||||
the delivered messages.
|
||||
|
||||
\param target Target of the message(s).
|
||||
\param message The message to be sent to the target.
|
||||
\param interval Period of time before the first message is sent and
|
||||
between messages (if more than one shall be sent) in microseconds.
|
||||
\param count Specifies 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.
|
||||
\param replyTo Target replies to the delivered message(s) shall be sent to.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMessageRunner::~BMessageRunner()
|
||||
\brief Frees all resources associated with the object.
|
||||
|
||||
\since BeOS R5
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BMessageRunner::InitCheck() const
|
||||
\brief Returns the initialization status.
|
||||
|
||||
\note As soon as the last message is sent, the message runner
|
||||
becomes unusable. InitCheck() will still return \c B_OK, but
|
||||
SetInterval(), SetCount() and GetInfo() will all fail.
|
||||
|
||||
\return \c B_OK if the object was properly initialized or an error code
|
||||
otherwise.
|
||||
|
||||
\since BeOS R5
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BMessageRunner::SetInterval(bigtime_t interval)
|
||||
\brief Sets the interval of time between messages.
|
||||
|
||||
\param interval The new interval in microseconds.
|
||||
|
||||
\return A status code, \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The message runner was not properly initialized.
|
||||
\retval B_BAD_VALUE \a interval was \c 0 or negative, or the message runner
|
||||
had already sent all messages and became unusable.
|
||||
|
||||
\since BeOS R5
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BMessageRunner::SetCount(int32 count)
|
||||
\brief Sets the number of times message should be sent.
|
||||
|
||||
\param count Specifies 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.
|
||||
|
||||
\return A status code, \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The message runner was not properly initialized.
|
||||
\retval B_BAD_VALUE \a interval was \c 0 or negative, or the message runner
|
||||
had already sent all messages and became unusable.
|
||||
|
||||
\since BeOS R5
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BMessageRunner::GetInfo(bigtime_t* interval,
|
||||
int32* count) const
|
||||
\brief Returns the time interval between two messages and the number of
|
||||
times the message has still to be sent.
|
||||
|
||||
Both parameters (\a interval and \a count) may be \c NULL.
|
||||
|
||||
\param interval Pointer to a pre-allocated bigtime_t variable to be set
|
||||
to the time interval. May be \c NULL.
|
||||
\param count Pointer to a pre-allocated int32 variable to be set
|
||||
to the number of times the message has still to be sent.
|
||||
May be \c NULL.
|
||||
|
||||
\return A status code, \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \a interval was 0 or negative, or the message runner
|
||||
had already sent all messages and became unusable.
|
||||
|
||||
\since BeOS R5
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BMessageRunner::StartSending(BMessenger target,
|
||||
const BMessage* message, bigtime_t interval, int32 count)
|
||||
\brief Creates and initializes a detached BMessageRunner and instructs the
|
||||
system roster to send the specified \a message to the \a target
|
||||
\a count times every \a interval microseconds, reply messages are
|
||||
sent to \c be_app_messenger.
|
||||
|
||||
You cannot alter the runner after the creation, and it will be deleted
|
||||
automatically the last message is sent.
|
||||
|
||||
\param target Target of the message(s).
|
||||
\param message The message to be sent to the target.
|
||||
\param interval Period of time before the first message is sent and
|
||||
between messages (if more than one shall be sent) in microseconds.
|
||||
\param count Specifies 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
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BMessageRunner::StartSending(BMessenger target,
|
||||
const BMessage* message, bigtime_t interval, int32 count,
|
||||
BMessenger replyTo)
|
||||
\brief Creates and initializes a detached BMessageRunner and instructs the
|
||||
system roster to send the specified \a message to the \a target
|
||||
\a count times every \a interval microseconds.
|
||||
|
||||
You cannot alter the runner after the creation, and it will be deleted
|
||||
automatically once the last message is sent.
|
||||
|
||||
\param target Target of the message(s).
|
||||
\param message The message to be sent to the target.
|
||||
\param interval Period of time before the first message is sent and
|
||||
between messages (if more than one shall be sent) in microseconds.
|
||||
\param count Specifies 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.
|
||||
\param replyTo Target replies to the delivered message(s) shall be sent to.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
Reference in New Issue
Block a user