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