[haiku-commits] haiku: hrev48691 - src/kits/app docs/user/app headers/os/app
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Fri, 16 Jan 2015 22:43:59 +0100 (CET)
hrev48691 adds 3 changesets to branch 'master'
old head: 14d19200394fd9a4b9186d1dd49439f891428533
new head: fd3c25a9283b926acfcee45c63901ea56c42362a
overview:
http://cgit.haiku-os.org/haiku/log/?qt=range&q=fd3c25a9283b+%5E14d19200394f
----------------------------------------------------------------------------
6fd099550fdf: Style fixes to Messenger, no functional change intended
973984649c10: Add BMessenger docs
fd3c25a9283b: Move the operator function docs over too
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
3 files changed, 651 insertions(+), 362 deletions(-)
docs/user/app/Messenger.dox | 507 ++++++++++++++++++++++++++++++++++++++++
headers/os/app/Messenger.h | 98 ++++----
src/kits/app/Messenger.cpp | 408 +++++++-------------------------
############################################################################
Commit: 6fd099550fdfdfb13b887006db7312e0134c47a5
URL: http://cgit.haiku-os.org/haiku/commit/?id=6fd099550fdf
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Fri Jan 16 21:33:42 2015 UTC
Style fixes to Messenger, no functional change intended
----------------------------------------------------------------------------
diff --git a/headers/os/app/Messenger.h b/headers/os/app/Messenger.h
index 3adec7d..7f5cbca 100644
--- a/headers/os/app/Messenger.h
+++ b/headers/os/app/Messenger.h
@@ -1,5 +1,5 @@
/*
- * Copyright 2001-2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2001-2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -13,51 +13,65 @@
#include <ByteOrder.h>
#include <Message.h>
+
class BHandler;
class BLooper;
-
class BMessenger {
-public:
- BMessenger();
- BMessenger(const char *signature, team_id team = -1,
- status_t *result = NULL);
- BMessenger(const BHandler *handler, const BLooper *looper = NULL,
- status_t *result = NULL);
- BMessenger(const BMessenger &from);
- ~BMessenger();
+public:
+
BMessenger();
+
BMessenger(const char* signature,
+
team_id team = -1,
+
status_t* result = NULL);
+
BMessenger(const BHandler* handler,
+
const BLooper* looper = NULL,
+
status_t* result = NULL);
+
BMessenger(const BMessenger& other);
+
~BMessenger();
// Target
- bool IsTargetLocal() const;
- BHandler *Target(BLooper **looper) const;
- bool LockTarget() const;
- status_t LockTargetWithTimeout(bigtime_t timeout) const;
+ bool IsTargetLocal()
const;
+ BHandler* Target(BLooper
**looper) const;
+ bool LockTarget()
const;
+ status_t
LockTargetWithTimeout(
+
bigtime_t timeout) const;
// Message sending
- status_t SendMessage(uint32 command, BHandler *replyTo = NULL) const;
- status_t SendMessage(BMessage *message, BHandler *replyTo = NULL,
- bigtime_t timeout =
B_INFINITE_TIMEOUT) const;
- status_t SendMessage(BMessage *message, BMessenger replyTo,
- bigtime_t timeout =
B_INFINITE_TIMEOUT) const;
- status_t SendMessage(uint32 command, BMessage *reply) const;
- status_t SendMessage(BMessage *message, BMessage *reply,
- bigtime_t deliveryTimeout =
B_INFINITE_TIMEOUT,
- bigtime_t replyTimeout =
B_INFINITE_TIMEOUT) const;
+ status_t
SendMessage(uint32 command,
+
BHandler* replyTo = NULL) const;
+ status_t
SendMessage(BMessage* message,
+
BHandler* replyTo = NULL,
+
bigtime_t timeout
+
= B_INFINITE_TIMEOUT) const;
+ status_t
SendMessage(BMessage* message,
+
BMessenger replyTo,
+
bigtime_t timeout
+
= B_INFINITE_TIMEOUT) const;
+ status_t
SendMessage(uint32 command,
+
BMessage* reply) const;
+ status_t
SendMessage(BMessage* message,
+
BMessage* reply,
+
bigtime_t deliveryTimeout
+
= B_INFINITE_TIMEOUT,
+
bigtime_t replyTimeout
+
= B_INFINITE_TIMEOUT) const;
// Operators and misc
- status_t SetTo(const char *signature, team_id team = -1);
- status_t SetTo(const BHandler *handler, const BLooper *looper = NULL);
+ status_t SetTo(const
char* signature,
+
team_id team = -1);
+ status_t SetTo(const
BHandler* handler,
+
const BLooper* looper = NULL);
- BMessenger &operator=(const BMessenger &from);
- bool operator==(const BMessenger &other) const;
+ BMessenger& operator=(const
BMessenger& other);
+ bool
operator==(const BMessenger& other) const;
- bool IsValid() const;
- team_id Team() const;
+ bool IsValid() const;
+ team_id Team() const;
- uint32 HashValue() const;
+ uint32 HashValue()
const;
//----- Private or reserved -----------------------------------------
@@ -66,20 +80,24 @@ public:
private:
friend class Private;
- void _SetTo(team_id team, port_id port, int32 token);
- void _InitData(const char *signature, team_id team, status_t *result);
- void _InitData(const BHandler *handler, const BLooper *looper,
- status_t *result);
+ void _SetTo(team_id
team, port_id port,
+
int32 token);
+ void _InitData(const
char* signature,
+
team_id team, status_t* result);
+ void _InitData(const
BHandler* handler,
+
const BLooper *looper,
+
status_t* result);
private:
- port_id fPort;
- int32 fHandlerToken;
- team_id fTeam;
+ port_id fPort;
+ int32 fHandlerToken;
+ team_id fTeam;
- int32 _reserved[3];
+ int32 _reserved[3];
};
-bool operator<(const BMessenger &a, const BMessenger &b);
-bool operator!=(const BMessenger &a, const BMessenger &b);
+bool operator<(const BMessenger& a, const BMessenger& b);
+bool operator!=(const BMessenger& a, const BMessenger& b);
+
#endif // _MESSENGER_H
diff --git a/src/kits/app/Messenger.cpp b/src/kits/app/Messenger.cpp
index 9d787ee..3549647 100644
--- a/src/kits/app/Messenger.cpp
+++ b/src/kits/app/Messenger.cpp
@@ -1,5 +1,5 @@
/*
- * Copyright 2001-2011, Haiku.
+ * Copyright 2001-2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -42,8 +42,6 @@ enum {
};
-/*! \brief Creates an unitialized BMessenger.
-*/
BMessenger::BMessenger()
:
fPort(-1),
@@ -53,21 +51,7 @@ BMessenger::BMessenger()
}
-/*! \brief Creates a BMessenger and initializes it to target the already
- running application identified by its signature and/or team ID.
-
- When only a signature is given, and multiple instances of the
application
- are running it is undeterminate 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 initilization 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.
-*/
-BMessenger::BMessenger(const char *signature, team_id team, status_t *result)
+BMessenger::BMessenger(const char* signature, team_id team, status_t* result)
:
fPort(-1),
fHandlerToken(B_NULL_TOKEN),
@@ -77,20 +61,6 @@ BMessenger::BMessenger(const char *signature, team_id team,
status_t *result)
}
-/*! \brief Creates a BMessenger and initializes it 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.
- \param result An optional pointer to a pre-allocated status_t into which
- the result of the initialization is written.
-*/
BMessenger::BMessenger(const BHandler* handler, const BLooper* looper,
status_t* _result)
:
@@ -102,22 +72,15 @@ BMessenger::BMessenger(const BHandler* handler, const
BLooper* looper,
}
-/*! \brief Creates a BMessenger and initializes it to have the same target
- as the supplied messemger.
-
- \param from The messenger to be copied.
-*/
-BMessenger::BMessenger(const BMessenger& from)
+BMessenger::BMessenger(const BMessenger& other)
:
- fPort(from.fPort),
- fHandlerToken(from.fHandlerToken),
- fTeam(from.fTeam)
+ fPort(other.fPort),
+ fHandlerToken(other.fHandlerToken),
+ fTeam(other.fTeam)
{
}
-/*! \brief Frees all resources associated with this object.
-*/
BMessenger::~BMessenger()
{
}
@@ -126,12 +89,6 @@ BMessenger::~BMessenger()
// #pragma mark - Target
-/*! \brief Returns whether or not the messenger's target lives within the
team
- of the caller.
-
- \return \c true, if the object is properly initialized and its target
- lives within the caller's team, \c false otherwise.
-*/
bool
BMessenger::IsTargetLocal() const
{
@@ -139,23 +96,10 @@ BMessenger::IsTargetLocal() 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.
-*/
-BHandler *
+BHandler*
BMessenger::Target(BLooper** _looper) const
{
- BHandler *handler = NULL;
+ BHandler* handler = NULL;
if (IsTargetLocal()
&& (fHandlerToken > B_NULL_TOKEN
|| fHandlerToken == B_PREFERRED_TOKEN)) {
@@ -170,21 +114,10 @@ BMessenger::Target(BLooper** _looper) 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 could be locked successfully, \c false,
if
- the messenger is not properly initialized, the target
is remote,
- or the targeted looper is invalid.
-*/
bool
BMessenger::LockTarget() const
{
- BLooper *looper = NULL;
+ BLooper* looper = NULL;
Target(&looper);
if (looper != NULL && looper->Lock()) {
if (looper->fMsgPort == fPort)
@@ -198,132 +131,59 @@ 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::LockWithTimeout() on the looper
afterwards.
-
- \see BLooper::LockWithTimeout() for details.
-
- \return
- - \c B_OK, if the looper could be locked successfully,
- - \c B_BAD_VALUE, if the messenger is not properly initialized,
- the target is remote, or the targeted looper is invalid,
- - other error codes returned by BLooper::LockWithTimeout().
-*/
status_t
BMessenger::LockTargetWithTimeout(bigtime_t timeout) const
{
- BLooper *looper = NULL;
+ BLooper* looper = NULL;
Target(&looper);
if (looper == NULL)
return B_BAD_VALUE;
- status_t error = looper->LockWithTimeout(timeout);
+ status_t result = looper->LockWithTimeout(timeout);
- if (error == B_OK && looper->fMsgPort != fPort) {
+ if (result == B_OK && looper->fMsgPort != fPort) {
looper->Unlock();
return B_BAD_PORT_ID;
}
- return error;
+ return result;
}
// #pragma mark - Message sending
-/*! \brief Delivers a BMessage synchronously to the messenger's target,
- without waiting for a reply.
-
- 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
- - \c B_OK: Everything went fine.
- - \c B_BAD_PORT_ID: The messenger is not properly initialized or its
- target doesn't exist anymore.
-*/
status_t
-BMessenger::SendMessage(uint32 command, BHandler *replyTo) const
+BMessenger::SendMessage(uint32 command, BHandler* replyTo) const
{
BMessage message(command);
return SendMessage(&message, replyTo);
}
-/*! \brief Delivers a BMessage synchronously to the messenger's target,
- without waiting for a reply.
-
- 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.
-
- \param message The message to be sent.
- \param replyTo The handler to which a reply to the message shall be
sent.
- May be \c NULL.
- \param timeout A timeout for the delivery of the message.
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_PORT_ID: The messenger is not properly initialized or its
- target doesn't exist anymore.
- - \c B_WOULD_BLOCK: A delivery timeout of 0 was supplied and the target
- port was full when trying to deliver the message.
- - \c B_TIMED_OUT: The timeout expired while trying to deliver the
- message.
-*/
status_t
-BMessenger::SendMessage(BMessage *message, BHandler *replyTo,
+BMessenger::SendMessage(BMessage* message, BHandler* replyTo,
bigtime_t timeout) const
{
DBG(OUT("BMessenger::SendMessage2(%.4s)\n", (char*)&message->what));
- status_t error = (message ? B_OK : B_BAD_VALUE);
- if (error == B_OK) {
+
+ status_t result = message != NULL ? B_OK : B_BAD_VALUE;
+ if (result == B_OK) {
BMessenger replyMessenger(replyTo);
- error = SendMessage(message, replyMessenger, timeout);
+ result = SendMessage(message, replyMessenger, timeout);
}
- DBG(OUT("BMessenger::SendMessage2() done: %lx\n", error));
- return error;
+
+ DBG(OUT("BMessenger::SendMessage2() done: %lx\n", result));
+
+ return result;
}
-/*! \brief Delivers a BMessage synchronously to the messenger's target,
- without waiting for a reply.
-
- 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.
-
- \param message The message to be sent.
- \param replyTo A messenger specifying the target for a reply to \a
message.
- \param timeout A timeout for the delivery of the message.
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_PORT_ID: The messenger is not properly initialized or its
- target doesn't exist anymore.
- - \c B_WOULD_BLOCK: A delivery timeout of 0 was supplied and the target
- port was full when trying to deliver the message.
- - \c B_TIMED_OUT: The timeout expired while trying to deliver the
- message.
-*/
status_t
-BMessenger::SendMessage(BMessage *message, BMessenger replyTo,
+BMessenger::SendMessage(BMessage* message, BMessenger replyTo,
bigtime_t timeout) const
{
- if (!message)
+ if (message == NULL)
return B_BAD_VALUE;
return BMessage::Private(message).SendMessage(fPort, fTeam,
fHandlerToken,
@@ -331,160 +191,77 @@ BMessenger::SendMessage(BMessage *message, BMessenger
replyTo,
}
-/*! \brief Delivers a BMessage synchronously to the messenger's target and
- waits for a reply.
-
- 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 into which the reply
- message will be copied.
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_PORT_ID: The messenger is not properly initialized or its
- target doesn't exist anymore.
- - \c B_NO_MORE_PORTS: All reply ports are in use.
-*/
status_t
-BMessenger::SendMessage(uint32 command, BMessage *reply) const
+BMessenger::SendMessage(uint32 command, BMessage* reply) const
{
BMessage message(command);
+
return SendMessage(&message, reply);
}
-/*! \brief Delivers a BMessage synchronously to the messenger's target and
- waits for a reply.
-
- 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.
-
- \param message The message to be sent.
- \param reply A pointer to a pre-allocated BMessage into which the reply
- message will be copied.
- \param deliveryTimeout A timeout for the delivery of the message.
- \param replyTimeout A timeout for waiting for the reply.
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_PORT_ID: The messenger is not properly initialized or its
- target doesn't exist anymore.
- - \c B_WOULD_BLOCK: A delivery timeout of 0 was supplied and the target
- port was full when trying to deliver the message.
- - \c B_TIMED_OUT: The timeout expired while trying to deliver the
- message.
- - \c B_NO_MORE_PORTS: All reply ports are in use.
-*/
status_t
-BMessenger::SendMessage(BMessage *message, BMessage *reply,
+BMessenger::SendMessage(BMessage* message, BMessage* reply,
bigtime_t deliveryTimeout, bigtime_t replyTimeout) const
{
if (message == NULL || reply == NULL)
return B_BAD_VALUE;
- status_t error = BMessage::Private(message).SendMessage(fPort, fTeam,
+ status_t result = BMessage::Private(message).SendMessage(fPort, fTeam,
fHandlerToken, reply, deliveryTimeout, replyTimeout);
- // Map this error for now:
- if (error == B_BAD_TEAM_ID)
- error = B_BAD_PORT_ID;
+ // map this result for now
+ if (result == B_BAD_TEAM_ID)
+ result = B_BAD_PORT_ID;
- return error;
+ return result;
}
// #pragma mark - Operators and misc
-/*! \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 undeterminate 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 initilization fails.
-
- \param signature The target application's signature. May be \c NULL.
- \param team The target application's team ID. May be < 0.
- \return The result of the reinitialization.
-*/
status_t
-BMessenger::SetTo(const char *signature, team_id team)
+BMessenger::SetTo(const char* signature, team_id team)
{
status_t result = B_OK;
_InitData(signature, team, &result);
+
return result;
}
-/*! \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 The result of the reinitialization.
-*/
status_t
BMessenger::SetTo(const BHandler* handler, const BLooper* looper)
{
status_t result = B_OK;
_InitData(handler, looper, &result);
+
return result;
}
-/*! \brief Makes this BMessenger a copy of the supplied one.
-
- \param from the messenger to be copied.
- \return A reference to this object.
-*/
-BMessenger &
-BMessenger::operator=(const BMessenger &from)
+BMessenger&
+BMessenger::operator=(const BMessenger& other)
{
- if (this != &from) {
- fPort = from.fPort;
- fHandlerToken = from.fHandlerToken;
- fTeam = from.fTeam;
+ if (this != &other) {
+ fPort = other.fPort;
+ fHandlerToken = other.fHandlerToken;
+ fTeam = other.fTeam;
}
+
return *this;
}
-/*! \brief Returns whether this and the supplied messenger have the same
- target.
-
- \param other The other messenger.
- \return \c true, if the messengers have the same target or if both
aren't
- properly initialzed, \c false otherwise.
-*/
bool
-BMessenger::operator==(const BMessenger &other) const
+BMessenger::operator==(const BMessenger& other) const
{
// Note: The fTeam fields are not compared.
- return fPort == other.fPort
- && fHandlerToken == other.fHandlerToken;
+ return fPort == other.fPort && fHandlerToken == other.fHandlerToken;
}
-/*! \brief Returns whether the messenger's target looper does still exist.
-
- It is not checked whether the target handler is also still existing.
-
- \return \c true, if the messenger's target looper does still exist,
- \c false otherwise.
-*/
bool
BMessenger::IsValid() const
{
@@ -493,10 +270,6 @@ BMessenger::IsValid() const
}
-/*! \brief Returns the ID of the team the messenger's target lives in.
-
- \return The team of the messenger's target.
-*/
team_id
BMessenger::Team() const
{
@@ -514,9 +287,9 @@ BMessenger::HashValue() const
// #pragma mark - Private or reserved
-/*! \brief Sets the messenger's team, target looper port and handler token.
+/*! Sets the messenger's team, target looper port and handler token.
- To target the preferred handler, use B_PREFERRED_TOKEN as token.
+ To target the preferred handler, use \c B_PREFERRED_TOKEN as token.
\param team The target's team.
\param port The target looper port.
@@ -531,7 +304,7 @@ BMessenger::_SetTo(team_id team, port_id port, int32 token)
}
-/*! \brief Initializes the BMessenger object's data given the signature
and/or
+/*! Initializes the BMessenger object's data given the signature and/or
team ID of a target.
When only a signature is given, and multiple instances of the
application
@@ -548,49 +321,51 @@ BMessenger::_SetTo(team_id team, port_id port, int32
token)
void
BMessenger::_InitData(const char* signature, team_id team, status_t* _result)
{
- status_t error = B_OK;
+ status_t result = B_OK;
+
// get an app_info
app_info info;
if (team < 0) {
// no team ID given
- if (signature) {
- error = be_roster->GetAppInfo(signature, &info);
+ if (signature != NULL) {
+ result = be_roster->GetAppInfo(signature, &info);
team = info.team;
// B_ERROR means that no application with the given
signature
// is running. But we are supposed to return
B_BAD_VALUE.
- if (error == B_ERROR)
- error = B_BAD_VALUE;
+ if (result == B_ERROR)
+ result = B_BAD_VALUE;
} else
- error = B_BAD_TYPE;
+ result = B_BAD_TYPE;
} else {
// a team ID is given
- error = be_roster->GetRunningAppInfo(team, &info);
+ result = be_roster->GetRunningAppInfo(team, &info);
// Compare the returned signature with the supplied one.
- if (error == B_OK && signature && strcasecmp(signature,
info.signature))
- error = B_MISMATCHED_VALUES;
+ if (result == B_OK && signature != NULL
+ && strcasecmp(signature, info.signature) != 0) {
+ result = B_MISMATCHED_VALUES;
+ }
}
// check whether the app flags say B_ARGV_ONLY
- if (error == B_OK && (info.flags & B_ARGV_ONLY)) {
- error = B_BAD_TYPE;
+ if (result == B_OK && (info.flags & B_ARGV_ONLY) != 0) {
+ result = B_BAD_TYPE;
// Set the team ID nevertheless -- that's what Be's
implementation
// does. Don't know, if that is a bug, but at least it doesn't
harm.
fTeam = team;
}
// init our members
- if (error == B_OK) {
+ if (result == B_OK) {
fTeam = team;
fPort = info.port;
fHandlerToken = B_PREFERRED_TOKEN;
}
- // return the error
- if (_result)
- *_result = error;
+ // return the result
+ if (_result != NULL)
+ *_result = result;
}
-/*! \brief Initializes the BMessenger to target the local BHandler and/or
- BLooper.
+/*! Initializes the 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
@@ -601,43 +376,46 @@ BMessenger::_InitData(const char* signature, team_id
team, status_t* _result)
\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.
+ the result of the initialization is written.
*/
void
BMessenger::_InitData(const BHandler* handler, const BLooper* looper,
status_t* _result)
{
- status_t error = (handler || looper ? B_OK : B_BAD_VALUE);
- if (error == B_OK) {
- if (handler) {
+ status_t result = handler || looper != NULL ? B_OK : B_BAD_VALUE;
+ if (result == B_OK) {
+ if (handler != NULL) {
// BHandler is given, check/retrieve the looper.
- if (looper) {
+ if (looper != NULL) {
if (handler->Looper() != looper)
- error = B_MISMATCHED_VALUES;
+ result = B_MISMATCHED_VALUES;
} else {
looper = handler->Looper();
if (looper == NULL)
- error = B_MISMATCHED_VALUES;
+ result = B_MISMATCHED_VALUES;
}
}
+
// set port, token,...
- if (error == B_OK) {
+ if (result == B_OK) {
AutoLocker<BLooperList> locker(gLooperList);
if (locker.IsLocked() &&
gLooperList.IsLooperValid(looper)) {
fPort = looper->fMsgPort;
- fHandlerToken = (handler
- ? _get_object_token_(handler) :
B_PREFERRED_TOKEN);
+ fHandlerToken = handler != NULL
+ ? _get_object_token_(handler)
+ : B_PREFERRED_TOKEN;
fTeam = looper->Team();
} else
- error = B_BAD_VALUE;
+ result = B_BAD_VALUE;
}
}
- if (_result)
- *_result = error;
+
+ if (_result != NULL)
+ *_result = result;
}
-/*! \brief Returns whether the first one of two BMessengers is less than the
+/*! Returns whether the first one of two BMessengers is less than the
second one.
This method defines an order on BMessengers based on their member
@@ -645,10 +423,11 @@ BMessenger::_InitData(const BHandler* handler, const
BLooper* looper,
\param a The first messenger.
\param b The second messenger.
+
\return \c true, if \a a is less than \a b, \c false otherwise.
*/
bool
-operator<(const BMessenger &_a, const BMessenger &_b)
+operator<(const BMessenger& _a, const BMessenger& _b)
{
BMessenger::Private a(const_cast<BMessenger&>(_a));
BMessenger::Private b(const_cast<BMessenger&>(_b));
@@ -667,15 +446,16 @@ operator<(const BMessenger &_a, const BMessenger &_b)
}
-/*! \brief Returns whether two BMessengers have not the same target.
+/*! Returns whether two BMessengers have not the same target.
\param a The first messenger.
\param b The second messenger.
+
\return \c false, if \a a and \a b have the same targets or are both not
- properly initialized, \c true otherwise.
+ properly initialized, \c true otherwise.
*/
bool
-operator!=(const BMessenger &a, const BMessenger &b)
+operator!=(const BMessenger& a, const BMessenger& b)
{
return !(a == b);
}
############################################################################
Commit: 973984649c10807744ce67766947e8f76197e18c
URL: http://cgit.haiku-os.org/haiku/commit/?id=973984649c10
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Fri Jan 16 21:34:00 2015 UTC
Add BMessenger docs
----------------------------------------------------------------------------
diff --git a/docs/user/app/Messenger.dox b/docs/user/app/Messenger.dox
new file mode 100644
index 0000000..201d230
--- /dev/null
+++ b/docs/user/app/Messenger.dox
@@ -0,0 +1,481 @@
+/*
+ * Copyright 2001-2015 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * John Scipione, jscipione@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ *
+ * 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.
+*/
+
+
+/*!
+ \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 BMessenger's target (i.e. BLooper::PostMessage()).
+
+ 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 \c what parameter set to \a command
+ synchronously to the messenger's target, without waiting for a
reply.
+
+ 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 BMessage synchronously to the messenger's target,
+ without waiting for a reply.
+
+ 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.
+
+ \param message The message to be sent.
+ \param replyTo The handler to which a reply to the message shall be
sent.
+ May be \c NULL.
+ \param timeout A timeout for the delivery of the message.
+
+ \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 BMessage synchronously to the messenger's target,
+ without waiting for a reply.
+
+ 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.
+
+ \param message The message to be sent.
+ \param replyTo A messenger specifying the target for a reply to \a
message.
+ \param timeout A timeout for the delivery of the message.
+
+ \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 \c what parameter set to \a command
+ synchronously to the messenger's target and waits for a reply.
+
+ 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 into which the reply
+ message will be copied.
+
+ \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 BMessage synchronously to the messenger's target and
+ waits for a reply.
+
+ 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.
+
+ \param message The message to be sent.
+ \param reply A pointer to a pre-allocated BMessage into which the reply
+ message will be copied.
+ \param deliveryTimeout A timeout for the delivery of the message.
+ \param replyTimeout A timeout for waiting for the reply.
+
+ \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
+*/
############################################################################
Revision: hrev48691
Commit: fd3c25a9283b926acfcee45c63901ea56c42362a
URL: http://cgit.haiku-os.org/haiku/commit/?id=fd3c25a9283b
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Fri Jan 16 21:42:45 2015 UTC
Move the operator function docs over too
----------------------------------------------------------------------------
diff --git a/docs/user/app/Messenger.dox b/docs/user/app/Messenger.dox
index 201d230..1ba3825 100644
--- a/docs/user/app/Messenger.dox
+++ b/docs/user/app/Messenger.dox
@@ -16,7 +16,8 @@
\file Messenger.h
\ingroup app
\ingroup libbe
- \brief Provides the BMessenger class.
+ \brief Provides the BMessenger class and some BMessenger operator
+ functions.
*/
@@ -479,3 +480,28 @@
\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.
+*/
diff --git a/src/kits/app/Messenger.cpp b/src/kits/app/Messenger.cpp
index 3549647..f46c4cb 100644
--- a/src/kits/app/Messenger.cpp
+++ b/src/kits/app/Messenger.cpp
@@ -415,17 +415,9 @@ BMessenger::_InitData(const BHandler* handler, const
BLooper* looper,
}
-/*! Returns whether the first one of two BMessengers is less than the
- second one.
+// #pragma mark - Operator functions
- 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 is less than \a b, \c false otherwise.
-*/
bool
operator<(const BMessenger& _a, const BMessenger& _b)
{
@@ -446,14 +438,6 @@ operator<(const BMessenger& _a, const BMessenger& _b)
}
-/*! Returns whether two BMessengers have not the same target.
-
- \param a The first messenger.
- \param b The second messenger.
-
- \return \c false, if \a a and \a b have the same targets or are both not
- properly initialized, \c true otherwise.
-*/
bool
operator!=(const BMessenger& a, const BMessenger& b)
{
Other related posts:
- » [haiku-commits] haiku: hrev48691 - src/kits/app docs/user/app headers/os/app - jscipione
