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*/ 268