docs/user/app/MessageRunner.dox

   1 /*
   2  * Copyright 2001-2015 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              John Scipione, jscipione@gmail.com
   7  *              Ingo Weinhold, bonefish@users.sf.net
   8  *
   9  * Corresponds to:
  10  *              headers/os/app/MessageRunner.h  hrev48689
  11  *              src/kits/app/MessageRunner.cpp  hrev48689
  12  */
  13
  14
  15 /*!
  16         \file MessageRunner.h
  17         \ingroup app
  18         \ingroup libbe
  19         \brief Provides the BMessageRunner class.
  20 */
  21
  22
  23 /*!
  24         \class BMessageRunner
  25         \ingroup app
  26         \ingroup libbe
  27         \brief Provides a mechanism for sending one or more messages
  28                to a messenger at a specified interval and receive
  29                reply messages.
  30
  31         The application that creates the BMessageRunner can specify the message,
  32         the BMessenger to send the message to, how often to send the message,
  33         how many times to send the message, and the BMessenger to send reply
  34         messages from.
  35
  36         The system roster handles dispatching the messages to the appropriate
  37         messengers at the specified time intervals. The target for any reply
  38         messages is \c be_app_messenger by default, or it can be specified in the
  39         constructor.
  40
  41         After initializing a BMessageRunner, the initialization can and should be
  42         checked by calling InitCheck(). BMessageRunner will not take ownership of
  43         the message, you may freely change or delete the message after
  44         initialization.
  45
  46         The BMessageRunner can be reconfigured (to change the interval or count)
  47         by calling SetInterval() and SetCount(). This is useful if you want to stop
  48         a BMessageRunner from sending messages early or if messages are set to
  49         be sent forever.
  50
  51         \since BeOS R5
  52 */
  53
  54
  55 /*!
  56         \fn BMessageRunner::BMessageRunner(BMessenger target,
  57                 const BMessage* message, bigtime_t interval, int32 count)
  58         \brief Creates and initializes a new BMessageRunner and instructs the
  59                system roster to send the specified \a message to the \a target
  60                \a count times every \a interval microseconds, reply messages are
  61                sent to \c be_app_messenger.
  62
  63         \param target The target of the message(s).
  64         \param message The message to be sent to the target.
  65         \param interval Period of time before the first message is sent and
  66                between messages (if more than one shall be sent) in microseconds.
  67         \param count Specifies how many times the message shall be sent.
  68                A negative value indicates that the message will be sent
  69                forever, or until the BMessageRunner is reconfigured or deleted.
  70
  71         \since BeOS R5
  72 */
  73
  74
  75 /*!
  76         \fn BMessageRunner::BMessageRunner(BMessenger target,
  77                 const BMessage& message, bigtime_t interval, int32 count)
  78         \brief Creates and initializes a new BMessageRunner and instructs the
  79                system roster to send the specified \a message to the \a target
  80                \a count times every \a interval microseconds, reply messages are
  81                sent to \c be_app_messenger.
  82
  83         \param target Target of the message(s).
  84         \param message The message to be sent to the target.
  85         \param interval Period of time before the first message is sent and
  86                between messages (if more than one shall be sent) in microseconds.
  87         \param count Specifies how many times the message shall be sent.
  88                A negative value indicates that the message will be sent
  89                forever, or until the BMessageRunner is reconfigured or deleted.
  90
  91         \since Haiku R1
  92 */
  93
  94
  95 /*!
  96         \fn BMessageRunner::BMessageRunner(BMessenger target,
  97                 const BMessage* message, bigtime_t interval, int32 count,
  98                 BMessenger replyTo)
  99         \brief Creates and initializes a new BMessageRunner and instructs the
 100                system roster to send the specified \a message to the \a target
 101                \a count times every \a interval microseconds.
 102
 103         This constructor also allows you to specify the target for replies to
 104         the delivered messages.
 105
 106         \param target Target of the message(s).
 107         \param message The message to be sent to the target.
 108         \param interval Period of time before the first message is sent and
 109                between messages (if more than one shall be sent) in microseconds.
 110         \param count Specifies how many times the message shall be sent.
 111                A negative value indicates that the message will be sent
 112                forever, or until the BMessageRunner is reconfigured or deleted.
 113         \param replyTo Target replies to the delivered message(s) shall be sent to.
 114
 115         \since BeOS R5
 116 */
 117
 118
 119 /*!
 120         \fn BMessageRunner::BMessageRunner(BMessenger target,
 121                 const BMessage& message, bigtime_t interval, int32 count,
 122                 BMessenger replyTo)
 123         \brief Creates and initializes a new BMessageRunner and instructs the
 124                system roster to send the specified \a message to the \a target
 125                \a count times every \a interval microseconds.
 126
 127         This constructor also allows you to specify the target for replies to
 128         the delivered messages.
 129
 130         \param target Target of the message(s).
 131         \param message The message to be sent to the target.
 132         \param interval Period of time before the first message is sent and
 133                between messages (if more than one shall be sent) in microseconds.
 134         \param count Specifies how many times the message shall be sent.
 135                A negative value indicates that the message will be sent
 136                forever, or until the BMessageRunner is reconfigured or deleted.
 137         \param replyTo Target replies to the delivered message(s) shall be sent to.
 138
 139         \since Haiku R1
 140 */
 141
 142
 143 /*!
 144         \fn BMessageRunner::~BMessageRunner()
 145         \brief Frees all resources associated with the object.
 146
 147         \since BeOS R5
 148 */
 149
 150
 151 /*!
 152         \fn status_t BMessageRunner::InitCheck() const
 153         \brief Returns the initialization status.
 154
 155         \note As soon as the last message is sent, the message runner
 156               becomes unusable. InitCheck() will still return \c B_OK, but
 157               SetInterval(), SetCount() and GetInfo() will all fail.
 158
 159         \return \c B_OK if the object was properly initialized or an error code
 160                 otherwise.
 161
 162         \since BeOS R5
 163 */
 164
 165
 166 /*!
 167         \fn status_t BMessageRunner::SetInterval(bigtime_t interval)
 168         \brief Sets the interval of time between messages.
 169
 170         \param interval The new interval in microseconds.
 171
 172         \return A status code, \c B_OK on success or an error code otherwise.
 173         \retval B_OK Everything went fine.
 174         \retval B_NO_INIT The message runner was not properly initialized.
 175         \retval B_BAD_VALUE \a interval was \c 0 or negative, or the message runner
 176                 had already sent all messages and became unusable.
 177
 178         \since BeOS R5
 179 */
 180
 181
 182 /*!
 183         \fn status_t BMessageRunner::SetCount(int32 count)
 184         \brief Sets the number of times message should be sent.
 185
 186         \param count Specifies how many times the message shall be sent.
 187                A negative value indicates that the message will be sent
 188                forever, or until the BMessageRunner is reconfigured or deleted.
 189
 190         \return A status code, \c B_OK on success or an error code otherwise.
 191         \retval B_OK Everything went fine.
 192         \retval B_NO_INIT The message runner was not properly initialized.
 193         \retval B_BAD_VALUE \a interval was \c 0 or negative, or the message runner
 194                 had already sent all messages and became unusable.
 195
 196         \since BeOS R5
 197 */
 198
 199
 200 /*!
 201         \fn status_t BMessageRunner::GetInfo(bigtime_t* interval,
 202                 int32* count) const
 203         \brief Returns the time interval between two messages and the number of
 204                times the message has still to be sent.
 205
 206         Both parameters (\a interval and \a count) may be \c NULL.
 207
 208         \param interval Pointer to a pre-allocated bigtime_t variable to be set
 209                to the time interval. May be \c NULL.
 210         \param count Pointer to a pre-allocated int32 variable to be set
 211                to the number of times the message has still to be sent.
 212                May be \c NULL.
 213
 214         \return A status code, \c B_OK on success or an error code otherwise.
 215         \retval B_OK Everything went fine.
 216         \retval B_BAD_VALUE \a interval was 0 or negative, or the message runner
 217                 had already sent all messages and became unusable.
 218
 219         \since BeOS R5
 220 */
 221
 222
 223 /*!
 224         \fn status_t BMessageRunner::StartSending(BMessenger target,
 225                 const BMessage* message, bigtime_t interval, int32 count)
 226         \brief Creates and initializes a detached BMessageRunner and instructs the
 227                system roster to send the specified \a message to the \a target
 228                \a count times every \a interval microseconds, reply messages are
 229                sent to \c be_app_messenger.
 230
 231         You cannot alter the runner after the creation, and it will be deleted
 232         automatically the last message is sent.
 233
 234         \param target Target of the message(s).
 235         \param message The message to be sent to the target.
 236         \param interval Period of time before the first message is sent and
 237                    between messages (if more than one shall be sent) in microseconds.
 238         \param count Specifies how many times the message shall be sent.
 239                A negative value indicates that the message will be sent
 240                forever, or until the BMessageRunner is reconfigured or deleted.
 241
 242         \since Haiku R1
 243 */
 244
 245
 246 /*!
 247         \fn status_t BMessageRunner::StartSending(BMessenger target,
 248                 const BMessage* message, bigtime_t interval, int32 count,
 249                 BMessenger replyTo)
 250         \brief Creates and initializes a detached BMessageRunner and instructs the
 251                system roster to send the specified \a message to the \a target
 252                \a count times every \a interval microseconds.
 253
 254         You cannot alter the runner after the creation, and it will be deleted
 255         automatically once the last message is sent.
 256
 257         \param target Target of the message(s).
 258         \param message The message to be sent to the target.
 259         \param interval Period of time before the first message is sent and
 260                between messages (if more than one shall be sent) in microseconds.
 261         \param count Specifies how many times the message shall be sent.
 262                A negative value indicates that the message will be sent
 263                forever, or until the BMessageRunner is reconfigured or deleted.
 264         \param replyTo Target replies to the delivered message(s) shall be sent to.
 265
 266         \since Haiku R1
 267 */