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/Messenger.h hrev48689 11 * src/kits/app/Messenger.cpp hrev48689 12 */ 13 14 15/*! 16 \file Messenger.h 17 \ingroup app 18 \ingroup libbe 19 \brief Provides the BMessenger class and some BMessenger operator 20 functions. 21*/ 22 23 24/*! 25 \class BMessenger 26 \ingroup app 27 \ingroup libbe 28 \brief A class to send messages to a target BLooper or BHandler. 29 30 A BMessenger can send messages to local and remote targets. If the target 31 belongs to the same team as the BMessenger it is a local target, otherwise 32 if the target lives in a separate address space it is a remote target. 33 34 The most significant (set of) method(s) in the class is SendMessage(), 35 which sends its message to the target. For a local target SendMessage() 36 is roughly equivalent in terms of efficiency to posting a message 37 directly to the messenger's target (i.e. BLooper::PostMessage()). 38 39 If you supply a target BMessenger or BHandler to SendMessage() the method 40 will return immediately after delivery and the response will be handled 41 asynchronously, otherwise the method will return once the reply has been 42 delivered or after a set timeout. 43 44 The global \a be_app_messenger pointer targets the main message 45 loop of \a be_app is automatically initialized for you when you create 46 a BApplication object, you can use it wherever a BMessenger is called for. 47 48 \since BeOS R3 49*/ 50 51 52/*! 53 \fn BMessenger::BMessenger() 54 \brief Creates an uninitialized BMessenger. 55 56 \since BeOS R3 57*/ 58 59 60/*! 61 \fn BMessenger::BMessenger(const char* signature, team_id team, 62 status_t* result) 63 \brief Creates a BMessenger and initializes it to target the already 64 running application identified by its signature and/or team ID. 65 66 When only a \a signature is given, and multiple instances of the application 67 are running it is indeterminate which one is chosen as the target. In case 68 only a \a team ID is passed, the target application is identified uniquely. 69 If both are supplied, the application identified by the \a team ID must have 70 a matching signature, otherwise the initialization fails. 71 72 \param signature The target application's signature. May be \c NULL. 73 \param team The target application's team ID. May be < 0. 74 \param result An optional pointer to a pre-allocated status_t into which 75 the result of the initialization is written. 76 77 \since BeOS R3 78*/ 79 80 81/*! 82 \fn BMessenger::BMessenger(const BHandler* handler, const BLooper* looper, 83 status_t* _result) 84 \brief Creates a BMessenger and initializes it to target the local 85 BHandler and/or BLooper. 86 87 When a \c NULL \a handler is supplied, the preferred handler in the 88 \a looper is targeted. If no \a looper is supplied the looper that \a handler 89 belongs to is used instead -- that means in particular, that the \a handler 90 must already belong to a looper. If both are supplied the \a handler must 91 belong to the \a looper. 92 93 \param handler The target handler. May be \c NULL. 94 \param looper The target looper. May be \c NULL. 95 \param _result An optional pointer to a pre-allocated status_t into which 96 the result of the initialization is written. 97 98 \since BeOS R3 99*/ 100 101 102/*! 103 \fn BMessenger::BMessenger(const BMessenger& other) 104 \brief Creates a BMessenger and initializes it to have the same target 105 as the supplied messenger. 106 107 \since BeOS R3 108*/ 109 110 111/*! 112 \fn BMessenger::~BMessenger() 113 \brief Frees all resources associated with this object. 114 115 \since BeOS R3 116*/ 117 118 119/*! 120 \name Target 121*/ 122 123 124//! @{ 125 126 127/*! 128 \fn bool BMessenger::IsTargetLocal() const 129 \brief Returns whether the messenger and target belong to the same team. 130 131 \return \c true if the messenger is properly initialized and its target 132 belong ot the same team, \c false if they reside in separate 133 address spaces. 134 135 \since BeOS R3 136*/ 137 138 139 140/*! 141 \fn BHandler* BMessenger::Target(BLooper** _looper) const 142 \brief Returns the handler and looper targeted by the messenger 143 (if the target is local). 144 145 The handler is returned directly, the looper by reference. If both are 146 \c NULL, the object is either not properly initialized, the target 147 objects have been deleted or the target is remote. If only the returned 148 handler is \c NULL, either the looper's preferred handler is targeted or 149 the handler has been deleted. 150 151 \param _looper A pointer to a pre-allocated BLooper pointer into which 152 the pointer to the targeted looper is written. 153 154 \return The BHandler targeted by the messenger. 155 156 \since BeOS R3 157*/ 158 159 160/*! 161 \fn bool BMessenger::LockTarget() const 162 \brief Locks the BLooper targeted by the messenger 163 (if the target is local). 164 165 This method is a shorthand for retrieving the targeted looper via 166 Target() and calling BLooper::Lock() on the looper afterwards. 167 168 \see BLooper::Lock() for details. 169 170 \return \c true, if the looper was locked successfully, \c false, if 171 the messenger was not properly initialized, the target was remote, 172 or the targeted looper was invalid. 173 174 \since BeOS R3 175*/ 176 177 178 179/*! 180 \fn status_t BMessenger::LockTargetWithTimeout(bigtime_t timeout) const 181 \brief Locks the BLooper targeted by the messenger with a \a timeout 182 (if the target is local). 183 184 This method is a shorthand for retrieving the targeted looper via 185 Target() and calling BLooper::LockWithTimeout() on the looper afterwards. 186 187 \see BLooper::LockWithTimeout() for details. 188 189 \return A status code, \c B_OK on success or an error code otherwise, 190 all other error codes returned by BLooper::LockWithTimeout(). 191 \retval B_OK if the looper could be locked successfully, 192 \retval B_BAD_VALUE if the messenger is not properly initialized, 193 the target is remote, or the targeted looper is invalid. 194 195 \see BLooper::LockWithTimeout() for more error codes. 196 197 \since BeOS R3 198*/ 199 200 201//! @} 202 203 204/*! 205 \name SendMessage 206*/ 207 208 209//! @{ 210 211 212/*! 213 \fn status_t BMessenger::SendMessage(uint32 command, BHandler* replyTo) const 214 \brief Delivers a BMessage with \a command \c what identifier to the 215 messenger's target. A response may be sent to the \a replyTo handler 216 asynchronously. 217 218 If the target's message port is full, the method waits indefinitely, until 219 space becomes available in the port. After delivery the method returns 220 immediately. It does not wait until the target processes the message or 221 even sends a reply. 222 223 \param command The what field of the message to deliver. 224 \param replyTo The handler to which a reply to the message shall be sent. 225 May be \c NULL. 226 227 \return A status code, \c B_OK on success or an error code otherwise. 228 \retval B_OK Everything went fine. 229 \retval B_BAD_PORT_ID The messenger is not properly initialized or its 230 target doesn't exist anymore. 231 232 \since BeOS R3 233*/ 234 235 236/*! 237 \fn status_t BMessenger::SendMessage(BMessage* message, BHandler* replyTo, 238 bigtime_t timeout) const 239 \brief Delivers a \a message to the messenger's target. A response message 240 may be sent back to the \a replyTo handler asynchronously. 241 242 A copy of the supplied message is sent and the caller retains ownership 243 of \a message. 244 245 If the target's message port is full, the method waits until space becomes 246 available in the port or the specified timeout occurs (whichever happens 247 first). After delivery the method returns immediately. It does not wait 248 until the target processes the message or even sends a reply. 249 250 This method does not return by default until the message has been delivered. 251 You can set a delivery \a timeout in microseconds. 252 253 \param message The message to be sent. 254 \param replyTo The handler for a response message to be sent. 255 May be \c NULL. 256 \param timeout The message delivery timeout in microseconds. (optional) 257 258 \return A status code, \c B_OK on success or an error code otherwise. 259 \retval B_OK Everything went fine. 260 \retval B_BAD_PORT_ID The messenger was not properly initialized or its 261 target didn't exist. 262 \retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target 263 port was full when trying to deliver the message. 264 \retval B_TIMED_OUT The timeout expired while trying to deliver the 265 message. 266 267 \since BeOS R3 268*/ 269 270 271/*! 272 \fn status_t BMessenger::SendMessage(BMessage* message, BMessenger replyTo, 273 bigtime_t timeout) const 274 \brief Delivers a \a message to the messenger's target. A response message 275 may be sent back to the \a replyTo messenger's target asynchronously. 276 277 A copy of the supplied message is sent and the caller retains ownership 278 of \a message. 279 280 If the target's message port is full, the method waits until space becomes 281 available in the port or the specified timeout occurs (whichever happens 282 first). After delivery the method returns immediately. It does not wait 283 until the target processes the message or even sends a reply. 284 285 This method does not return by default until the message has been delivered. 286 You can set a delivery \a timeout in microseconds. 287 288 \param message The message to be sent. 289 \param replyTo A messenger specifying the target for a response message. 290 \param timeout The message delivery timeout in microseconds. (optional) 291 292 \return A status code, \c B_OK on success or an error code otherwise. 293 \retval B_OK Everything went fine. 294 \retval B_BAD_PORT_ID The messenger was not properly initialized or its 295 target didn't exist. 296 \retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target 297 port was full when trying to deliver the message. 298 \retval B_TIMED_OUT The timeout expired while trying to deliver the 299 message. 300 301 \since BeOS R4 302*/ 303 304 305/*! 306 \fn status_t BMessenger::SendMessage(uint32 command, BMessage* reply) const 307 \brief Delivers a BMessage with \a command \c what identifier to the 308 messenger's target and waits for a \a reply BMessage synchronously. 309 310 The method does wait for a reply. The reply message is copied into 311 \a reply. If the target doesn't send a reply, the \c what field of 312 \a reply is set to \c B_NO_REPLY. 313 314 \param command The what field of the message to deliver. 315 \param reply A pointer to a pre-allocated BMessage object which the reply 316 message will be copied into. 317 318 \return A status code, \c B_OK on success or an error code otherwise. 319 \retval B_OK Everything went fine. 320 \retval B_BAD_PORT_ID The messenger was not properly initialized or its 321 target didn't exist. 322 \retval B_NO_MORE_PORTS All reply ports were in use. 323 324 \since BeOS R3 325*/ 326 327 328/*! 329 \fn status_t BMessenger::SendMessage(BMessage* message, BMessage* reply, 330 bigtime_t deliveryTimeout, bigtime_t replyTimeout) const 331 \brief Delivers a \a message to the messenger's target and waits for a 332 \a reply to come back synchronously. 333 334 A copy of the supplied message is sent and the caller retains ownership 335 of \a message. 336 337 The method does wait for a reply. The reply message is copied into 338 \a reply. If the target doesn't send a reply or if a reply timeout occurs, 339 the \c what field of \a reply is set to \c B_NO_REPLY. 340 341 This method does not return by default until the message has been delivered 342 and the reply has come back. You can set a \a deliveryTimeout and a 343 \a replyTimeout in microseconds. 344 345 \param message The message to be sent. 346 \param reply A pointer to a pre-allocated BMessage which the reply 347 message will be copied into. 348 \param deliveryTimeout The message delivery timeout in microseconds. 349 (optional) 350 \param replyTimeout The reply message timeout in microseconds. (optional) 351 352 \return A status code, \c B_OK on success or an error code otherwise. 353 \retval B_OK Everything went fine. 354 \retval B_BAD_PORT_ID The messenger was not properly initialized or its 355 target didn't exist. 356 \retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target 357 port was full when trying to deliver the message. 358 \retval B_TIMED_OUT The timeout expired while trying to deliver the 359 message. 360 \retval B_NO_MORE_PORTS All reply ports were in use. 361 362 \since BeOS R3 363*/ 364 365 366//! @} 367 368 369/*! 370 \name SetTo 371*/ 372 373 374//! @{ 375 376 377/*! 378 \fn status_t BMessenger::SetTo(const char* signature, team_id team) 379 \brief Reinitializes a BMessenger to target the already running application 380 identified by the supplied signature and/or team ID. 381 382 When only a signature is given, and multiple instances of the application 383 are running it is indeterminate which one is chosen as the target. In case 384 only a team ID is passed, the target application is identified uniquely. 385 If both are supplied, the application identified by the team ID must have 386 a matching signature, otherwise the initialization fails. 387 388 \param signature The target application's signature. May be \c NULL. 389 \param team The target application's team ID. May be negative. 390 391 \return A status code, \c B_OK if the reinitialization was successful or an 392 error code otherwise. 393 \retval B_OK The reinitialization was successful. 394 \retval B_BAD_VALUE No application with the given \a signature or \a team 395 ID was running. 396 \retval B_BAD_TYPE No \a team ID was given and the \a signature was \c NULL. 397 \retval B_MISMATCHED_VALUES The supplied \a signature and the signature of 398 the team didn't match. 399 400 \since Haiku R1 401*/ 402 403 404/*! 405 \fn status_t BMessenger::SetTo(const BHandler* handler, 406 const BLooper* looper) 407 \brief Reinitializes a BMessenger to target the local BHandler and/or 408 BLooper. 409 410 When a \c NULL handler is supplied, the preferred handler in the given 411 looper is targeted. If no looper is supplied the looper the given handler 412 belongs to is used -- that means in particular, that the handler must 413 already belong to a looper. If both are supplied the handler must actually 414 belong to looper. 415 416 \param handler The target handler. May be \c NULL. 417 \param looper The target looper. May be \c NULL. 418 419 \return A status code, \c B_OK if the reinitialization was successful or an 420 error code otherwise. 421 \retval B_OK The reinitialization was successful. 422 \retval B_BAD_VALUE Both \a handler and \a looper were \c NULL or invalid. 423 \retval B_MISMATCHED_VALUES The looper of the supplied \a handler and 424 \a looper didn't match. 425 426 \since Haiku R1 427*/ 428 429 430//! @} 431 432 433/*! 434 \name Operators 435*/ 436 437 438//! @{ 439 440 441/*! 442 \fn BMessenger& BMessenger::operator=(const BMessenger& other) 443 \brief Assignment operator, makes this BMessenger a copy of \a other. 444 445 \param other the messenger to be copied. 446 447 \return A reference to this object. 448 449 \since BeOS R3 450*/ 451 452 453/*! 454 \fn bool BMessenger::operator==(const BMessenger& other) const 455 \brief Comparison operator, returns whether this and \a other have the same 456 target. 457 458 \param other The messenger to be compared to. 459 460 \return \c true, if the messengers have the same target or if both aren't 461 properly initialized, \c false otherwise. 462 463 \since BeOS R3 464*/ 465 466 467//! @} 468 469 470/*! 471 \fn bool BMessenger::IsValid() const 472 \brief Returns whether the messenger's target looper still exists. 473 474 \warning This method does not check whether the target handler 475 also still exists. 476 477 \return \c true, if the messenger's target looper still exists, 478 \c false otherwise. 479 480 \since BeOS R3 481*/ 482 483 484/*! 485 \fn team_id BMessenger::Team() const 486 \brief Returns the ID of the team that the messenger's target belongs to. 487 488 \return The team of the messenger's target. 489 490 \since BeOS R3 491*/ 492 493 494/*! 495 \fn uint32 BMessenger::HashValue() const 496 \brief Returns a hash value that uniquely identifies the messenger. 497 498 \since Haiku R1 499*/ 500 501 502/*! 503 \fn bool operator<(const BMessenger& _a, const BMessenger& _b) 504 \brief Returns whether the first messenger is less than the second one. 505 506 This method defines an order on BMessengers based on their member 507 variables \c fPort, \c fHandlerToken and \c fPreferredTarget. 508 509 \param _a The first messenger. 510 \param _b The second messenger. 511 512 \return \c true, if \a a was less than \a b, \c false otherwise. 513*/ 514 515 516/*! 517 \fn bool operator!=(const BMessenger& a, const BMessenger& b) 518 \brief Returns whether two BMessengers do NOT have the same target. 519 520 \param a The first messenger. 521 \param b The second messenger. 522 523 \return \c false, if \a a and \a b had the same targets or both were not 524 properly initialized, \c true otherwise. 525*/ 526