151a4f7f93
... docs to make it clear which methods work synchronously and which work asynchronously. A small number of related edits are included as well as a couple of pedantic whitespace changes. Clarify sync vs. async reply handling better in BMessenger class description. Add The to make sentences. Change-Id: I3069934fc5e82dda25331e85884d6d0c0c100dfd Reviewed-on: https://review.haiku-os.org/c/haiku/+/2178 Reviewed-by: waddlesplash <waddlesplash@gmail.com>
526 lines
16 KiB
Plaintext
526 lines
16 KiB
Plaintext
/*
|
|
* Copyright 2001-2015 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* John Scipione, jscipione@gmail.com
|
|
* Ingo Weinhold, bonefish@users.sf.net
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/app/Messenger.h hrev48689
|
|
* src/kits/app/Messenger.cpp hrev48689
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Messenger.h
|
|
\ingroup app
|
|
\ingroup libbe
|
|
\brief Provides the BMessenger class and some BMessenger operator
|
|
functions.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BMessenger
|
|
\ingroup app
|
|
\ingroup libbe
|
|
\brief A class to send messages to a target BLooper or BHandler.
|
|
|
|
A BMessenger can send messages to local and remote targets. If the target
|
|
belongs to the same team as the BMessenger it is a local target, otherwise
|
|
if the target lives in a separate address space it is a remote target.
|
|
|
|
The most significant (set of) method(s) in the class is SendMessage(),
|
|
which sends its message to the target. For a local target SendMessage()
|
|
is roughly equivalent in terms of efficiency to posting a message
|
|
directly to the messenger's target (i.e. BLooper::PostMessage()).
|
|
|
|
If you supply a target BMessenger or BHandler to SendMessage() the method
|
|
will return immediately after delivery and the response will be handled
|
|
asynchronously, otherwise the method will return once the reply has been
|
|
delivered or after a set timeout.
|
|
|
|
The global \a be_app_messenger pointer targets the main message
|
|
loop of \a be_app is automatically initialized for you when you create
|
|
a BApplication object, you can use it wherever a BMessenger is called for.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessenger::BMessenger()
|
|
\brief Creates an uninitialized BMessenger.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessenger::BMessenger(const char* signature, team_id team,
|
|
status_t* result)
|
|
\brief Creates a BMessenger and initializes it to target the already
|
|
running application identified by its signature and/or team ID.
|
|
|
|
When only a \a signature is given, and multiple instances of the application
|
|
are running it is indeterminate which one is chosen as the target. In case
|
|
only a \a team ID is passed, the target application is identified uniquely.
|
|
If both are supplied, the application identified by the \a team ID must have
|
|
a matching signature, otherwise the initialization fails.
|
|
|
|
\param signature The target application's signature. May be \c NULL.
|
|
\param team The target application's team ID. May be < 0.
|
|
\param result An optional pointer to a pre-allocated status_t into which
|
|
the result of the initialization is written.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessenger::BMessenger(const BHandler* handler, const BLooper* looper,
|
|
status_t* _result)
|
|
\brief Creates a BMessenger and initializes it to target the local
|
|
BHandler and/or BLooper.
|
|
|
|
When a \c NULL \a handler is supplied, the preferred handler in the
|
|
\a looper is targeted. If no \a looper is supplied the looper that \a handler
|
|
belongs to is used instead -- that means in particular, that the \a handler
|
|
must already belong to a looper. If both are supplied the \a handler must
|
|
belong to the \a looper.
|
|
|
|
\param handler The target handler. May be \c NULL.
|
|
\param looper The target looper. May be \c NULL.
|
|
\param _result An optional pointer to a pre-allocated status_t into which
|
|
the result of the initialization is written.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessenger::BMessenger(const BMessenger& other)
|
|
\brief Creates a BMessenger and initializes it to have the same target
|
|
as the supplied messenger.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessenger::~BMessenger()
|
|
\brief Frees all resources associated with this object.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\name Target
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn bool BMessenger::IsTargetLocal() const
|
|
\brief Returns whether the messenger and target belong to the same team.
|
|
|
|
\return \c true if the messenger is properly initialized and its target
|
|
belong ot the same team, \c false if they reside in separate
|
|
address spaces.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
|
|
/*!
|
|
\fn BHandler* BMessenger::Target(BLooper** _looper) const
|
|
\brief Returns the handler and looper targeted by the messenger
|
|
(if the target is local).
|
|
|
|
The handler is returned directly, the looper by reference. If both are
|
|
\c NULL, the object is either not properly initialized, the target
|
|
objects have been deleted or the target is remote. If only the returned
|
|
handler is \c NULL, either the looper's preferred handler is targeted or
|
|
the handler has been deleted.
|
|
|
|
\param _looper A pointer to a pre-allocated BLooper pointer into which
|
|
the pointer to the targeted looper is written.
|
|
|
|
\return The BHandler targeted by the messenger.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BMessenger::LockTarget() const
|
|
\brief Locks the BLooper targeted by the messenger
|
|
(if the target is local).
|
|
|
|
This method is a shorthand for retrieving the targeted looper via
|
|
Target() and calling BLooper::Lock() on the looper afterwards.
|
|
|
|
\see BLooper::Lock() for details.
|
|
|
|
\return \c true, if the looper was locked successfully, \c false, if
|
|
the messenger was not properly initialized, the target was remote,
|
|
or the targeted looper was invalid.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::LockTargetWithTimeout(bigtime_t timeout) const
|
|
\brief Locks the BLooper targeted by the messenger with a \a timeout
|
|
(if the target is local).
|
|
|
|
This method is a shorthand for retrieving the targeted looper via
|
|
Target() and calling BLooper::LockWithTimeout() on the looper afterwards.
|
|
|
|
\see BLooper::LockWithTimeout() for details.
|
|
|
|
\return A status code, \c B_OK on success or an error code otherwise,
|
|
all other error codes returned by BLooper::LockWithTimeout().
|
|
\retval B_OK if the looper could be locked successfully,
|
|
\retval B_BAD_VALUE if the messenger is not properly initialized,
|
|
the target is remote, or the targeted looper is invalid.
|
|
|
|
\see BLooper::LockWithTimeout() for more error codes.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name SendMessage
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::SendMessage(uint32 command, BHandler* replyTo) const
|
|
\brief Delivers a BMessage with \a command \c what identifier to the
|
|
messenger's target. A response may be sent to the \a replyTo handler
|
|
asynchronously.
|
|
|
|
If the target's message port is full, the method waits indefinitely, until
|
|
space becomes available in the port. After delivery the method returns
|
|
immediately. It does not wait until the target processes the message or
|
|
even sends a reply.
|
|
|
|
\param command The what field of the message to deliver.
|
|
\param replyTo The handler to which a reply to the message shall 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_PORT_ID The messenger is not properly initialized or its
|
|
target doesn't exist anymore.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::SendMessage(BMessage* message, BHandler* replyTo,
|
|
bigtime_t timeout) const
|
|
\brief Delivers a \a message to the messenger's target. A response message
|
|
may be sent back to the \a replyTo handler asynchronously.
|
|
|
|
A copy of the supplied message is sent and the caller retains ownership
|
|
of \a message.
|
|
|
|
If the target's message port is full, the method waits until space becomes
|
|
available in the port or the specified timeout occurs (whichever happens
|
|
first). After delivery the method returns immediately. It does not wait
|
|
until the target processes the message or even sends a reply.
|
|
|
|
This method does not return by default until the message has been delivered.
|
|
You can set a delivery \a timeout in microseconds.
|
|
|
|
\param message The message to be sent.
|
|
\param replyTo The handler for a response message to be sent.
|
|
May be \c NULL.
|
|
\param timeout The message delivery timeout in microseconds. (optional)
|
|
|
|
\return A status code, \c B_OK on success or an error code otherwise.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_BAD_PORT_ID The messenger was not properly initialized or its
|
|
target didn't exist.
|
|
\retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target
|
|
port was full when trying to deliver the message.
|
|
\retval B_TIMED_OUT The timeout expired while trying to deliver the
|
|
message.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::SendMessage(BMessage* message, BMessenger replyTo,
|
|
bigtime_t timeout) const
|
|
\brief Delivers a \a message to the messenger's target. A response message
|
|
may be sent back to the \a replyTo messenger's target asynchronously.
|
|
|
|
A copy of the supplied message is sent and the caller retains ownership
|
|
of \a message.
|
|
|
|
If the target's message port is full, the method waits until space becomes
|
|
available in the port or the specified timeout occurs (whichever happens
|
|
first). After delivery the method returns immediately. It does not wait
|
|
until the target processes the message or even sends a reply.
|
|
|
|
This method does not return by default until the message has been delivered.
|
|
You can set a delivery \a timeout in microseconds.
|
|
|
|
\param message The message to be sent.
|
|
\param replyTo A messenger specifying the target for a response message.
|
|
\param timeout The message delivery timeout in microseconds. (optional)
|
|
|
|
\return A status code, \c B_OK on success or an error code otherwise.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_BAD_PORT_ID The messenger was not properly initialized or its
|
|
target didn't exist.
|
|
\retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target
|
|
port was full when trying to deliver the message.
|
|
\retval B_TIMED_OUT The timeout expired while trying to deliver the
|
|
message.
|
|
|
|
\since BeOS R4
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::SendMessage(uint32 command, BMessage* reply) const
|
|
\brief Delivers a BMessage with \a command \c what identifier to the
|
|
messenger's target and waits for a \a reply BMessage synchronously.
|
|
|
|
The method does wait for a reply. The reply message is copied into
|
|
\a reply. If the target doesn't send a reply, the \c what field of
|
|
\a reply is set to \c B_NO_REPLY.
|
|
|
|
\param command The what field of the message to deliver.
|
|
\param reply A pointer to a pre-allocated BMessage object which the reply
|
|
message will be copied into.
|
|
|
|
\return A status code, \c B_OK on success or an error code otherwise.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_BAD_PORT_ID The messenger was not properly initialized or its
|
|
target didn't exist.
|
|
\retval B_NO_MORE_PORTS All reply ports were in use.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::SendMessage(BMessage* message, BMessage* reply,
|
|
bigtime_t deliveryTimeout, bigtime_t replyTimeout) const
|
|
\brief Delivers a \a message to the messenger's target and waits for a
|
|
\a reply to come back synchronously.
|
|
|
|
A copy of the supplied message is sent and the caller retains ownership
|
|
of \a message.
|
|
|
|
The method does wait for a reply. The reply message is copied into
|
|
\a reply. If the target doesn't send a reply or if a reply timeout occurs,
|
|
the \c what field of \a reply is set to \c B_NO_REPLY.
|
|
|
|
This method does not return by default until the message has been delivered
|
|
and the reply has come back. You can set a \a deliveryTimeout and a
|
|
\a replyTimeout in microseconds.
|
|
|
|
\param message The message to be sent.
|
|
\param reply A pointer to a pre-allocated BMessage which the reply
|
|
message will be copied into.
|
|
\param deliveryTimeout The message delivery timeout in microseconds.
|
|
(optional)
|
|
\param replyTimeout The reply message timeout in microseconds. (optional)
|
|
|
|
\return A status code, \c B_OK on success or an error code otherwise.
|
|
\retval B_OK Everything went fine.
|
|
\retval B_BAD_PORT_ID The messenger was not properly initialized or its
|
|
target didn't exist.
|
|
\retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target
|
|
port was full when trying to deliver the message.
|
|
\retval B_TIMED_OUT The timeout expired while trying to deliver the
|
|
message.
|
|
\retval B_NO_MORE_PORTS All reply ports were in use.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name SetTo
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::SetTo(const char* signature, team_id team)
|
|
\brief Reinitializes a BMessenger to target the already running application
|
|
identified by the supplied signature and/or team ID.
|
|
|
|
When only a signature is given, and multiple instances of the application
|
|
are running it is indeterminate which one is chosen as the target. In case
|
|
only a team ID is passed, the target application is identified uniquely.
|
|
If both are supplied, the application identified by the team ID must have
|
|
a matching signature, otherwise the initialization fails.
|
|
|
|
\param signature The target application's signature. May be \c NULL.
|
|
\param team The target application's team ID. May be negative.
|
|
|
|
\return A status code, \c B_OK if the reinitialization was successful or an
|
|
error code otherwise.
|
|
\retval B_OK The reinitialization was successful.
|
|
\retval B_BAD_VALUE No application with the given \a signature or \a team
|
|
ID was running.
|
|
\retval B_BAD_TYPE No \a team ID was given and the \a signature was \c NULL.
|
|
\retval B_MISMATCHED_VALUES The supplied \a signature and the signature of
|
|
the team didn't match.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BMessenger::SetTo(const BHandler* handler,
|
|
const BLooper* looper)
|
|
\brief Reinitializes a BMessenger to target the local BHandler and/or
|
|
BLooper.
|
|
|
|
When a \c NULL handler is supplied, the preferred handler in the given
|
|
looper is targeted. If no looper is supplied the looper the given handler
|
|
belongs to is used -- that means in particular, that the handler must
|
|
already belong to a looper. If both are supplied the handler must actually
|
|
belong to looper.
|
|
|
|
\param handler The target handler. May be \c NULL.
|
|
\param looper The target looper. May be \c NULL.
|
|
|
|
\return A status code, \c B_OK if the reinitialization was successful or an
|
|
error code otherwise.
|
|
\retval B_OK The reinitialization was successful.
|
|
\retval B_BAD_VALUE Both \a handler and \a looper were \c NULL or invalid.
|
|
\retval B_MISMATCHED_VALUES The looper of the supplied \a handler and
|
|
\a looper didn't match.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Operators
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BMessenger& BMessenger::operator=(const BMessenger& other)
|
|
\brief Assignment operator, makes this BMessenger a copy of \a other.
|
|
|
|
\param other the messenger to be copied.
|
|
|
|
\return A reference to this object.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BMessenger::operator==(const BMessenger& other) const
|
|
\brief Comparison operator, returns whether this and \a other have the same
|
|
target.
|
|
|
|
\param other The messenger to be compared to.
|
|
|
|
\return \c true, if the messengers have the same target or if both aren't
|
|
properly initialized, \c false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\fn bool BMessenger::IsValid() const
|
|
\brief Returns whether the messenger's target looper still exists.
|
|
|
|
\warning This method does not check whether the target handler
|
|
also still exists.
|
|
|
|
\return \c true, if the messenger's target looper still exists,
|
|
\c false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn team_id BMessenger::Team() const
|
|
\brief Returns the ID of the team that the messenger's target belongs to.
|
|
|
|
\return The team of the messenger's target.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn uint32 BMessenger::HashValue() const
|
|
\brief Returns a hash value that uniquely identifies the messenger.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool operator<(const BMessenger& _a, const BMessenger& _b)
|
|
\brief Returns whether the first messenger is less than the second one.
|
|
|
|
This method defines an order on BMessengers based on their member
|
|
variables \c fPort, \c fHandlerToken and \c fPreferredTarget.
|
|
|
|
\param _a The first messenger.
|
|
\param _b The second messenger.
|
|
|
|
\return \c true, if \a a was less than \a b, \c false otherwise.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool operator!=(const BMessenger& a, const BMessenger& b)
|
|
\brief Returns whether two BMessengers do NOT have the same target.
|
|
|
|
\param a The first messenger.
|
|
\param b The second messenger.
|
|
|
|
\return \c false, if \a a and \a b had the same targets or both were not
|
|
properly initialized, \c true otherwise.
|
|
*/
|