BMessenger

Dérivé de : aucun

Déclaré dans : be/app/Messenger.h

Bibliothèque : libbe.so

Allocation : pile ou constructeur

Résumé

Un BMessenger représente et envoie des messages à un destinataire message ; le destinataire est un BLooper et, de manière optionnelle, un BHandler spécifique de ce looper. Le destinataire peut exister dans la même application que le BMessenger (destinataire local), ou peut se trouver dans une autre application (destinataire distant).

La fonction la plus significative du BMessenger's est SendMessage(), qui envoie l'argument BMessage au destinataire.

Pour un destinataire local, SendMessage() est en gros équivalent, du point de vue de l'efficacité, à poster un message directement au destinataire du BMessenger (c.a.d. BLooper::PostMessage()).

Le pointeur global de BMessenger be_app_messenger , qui cible la boucle de message principale de be_app , est automatiquement initialisé pour vous quand vous créez votre objet BApplication .. Vous pouvez l'utiliser partout où les BMessengers sont requis.

Constructeur et Destructeur

BMessenger()

	BMessenger(const BHandler *handler,       const BLooper *looper = NULL,       status_t *error = NULL) BMessenger(const char *signature,       team_id team = –1,       status_t *error = NULL) BMessenger(const BMessenger &messenger) BMessenger(void)

Crée un nouveau BMessenger et positionne son destinataire vers un looper/handler local, vers une application (en cours d'exécution) identifiée par signature ou team, ou encore vers le destinataire d'un quelconque autre messenger.

• Looper/handler. Pour cibler un looper, fournir un looper et passer un NULL handler. Quand le messager envoie un message, ce message est pris en charge par le looper préféré du handler. Si vous désirez que le message soit envoyé à un handler spécifique d'un looper, fournir un handler et passer un NULL looper. Le handler doit déjà être attaché au looper, et il ne peut changer de looper après la construction du BMessenger.

• Signature ou team. Si vous fournissez une signature mais laissez team à la valeur –1, le messager cible une application qui porte cette signature. (L'application doit déjà être en cours d'exécution ; Dans le cas de multiples instances d'une application active, l'instance exacte est indéterminée). Si vous fournissez une team mais pas de signature, vous ciblez exactement cette team, en ignorant la signature. En fournissant à la fois une team et une signature, vous pouvez spécifier l'instance particulière d'une application. Dans ce cas, team doit être une application possédant la signature appropriée.

  Les messages envoyés vers un destinataire distant sont reçus et pris en charge par l'objet BApplication de l'application distante.

Le BMessenger n'est pas le propriétaire du destinataire.

CODES RETOUR

Le constructeur affecte un code d'erreur à error (si ce dernier est fourni).

• B_OK. Le destinataire a été correctement désigné.

• B_BAD_VALUE. L'application identifiée par signature n'a pas été trouvée, ou handler et looper sont invalides tous les deux.

• B_BAD_TEAM_ID. Invalide team.

• B_MISMATCHED_VALUES. team n'est pas une signature d'application, ou handler est associé à un BLooper différent de looper.

• B_BAD_HANDLER. handler n'est pas associé à un BLooper.

~BMessenger()

	~BMessenger()

Libère le BMessenger ; le destinataire n'est pas affecté.

Fonctions Membre

IsTargetLocal() voir Target()

IsValid()

	bool IsValid(void) const

Retourne true si le looper destinataire, local ou distant, existe encore.

Cette fonction ne précise pas si le looper est réellement prêt à recevoir des messages, ou si le handler existe (s'il a été spécifié dans le constructeur). Autrement dit, un BMessenger valide n'apporte aucune garantie qu'un message atteindra réellement le destinataire.

LockTarget() , LockTargetWithTimeout()

	bool LockTarget(void) const status_t LockTargetWithTimeout(bigtime_t timeout) const

Ces fonctions sont uniquement applicables aux destinataires locaux.

Ces fonctions tentent de verrouiller le looper destinataire à la manière des fonctions BLooper de même nom (voir BLooper::LockTarget()). En plus des codes erreur déjà décrits, ces fonctions retournent respectivement false et B_BAD_VALUE si le destinataire n'est pas local, ou si le looper est de quelque manière invalide.

SendMessage()

status_t SendMessage(BMessage *message,       BMessage *reply,       bigtime_t deliveryTimeout = B_INFINITE_TIMEOUT,       bigtime_t replyTimeout = B_INFINITE_TIMEOUT) const status_t SendMessage(BMessage *message,       BHandler *replyHandler = NULL,       bigtime_t deliveryTimeout = B_INFINITE_TIMEOUT) const status_t SendMessage(BMessage *message,       BMessenger *replyMessenger,       bigtime_t deliveryTimeout = B_INFINITE_TIMEOUT) const status_t SendMessage(uint32 command, BMessage *reply) const status_t SendMessage(uint32 command, BHandler *replyHandler = NULL) const

Envoie une copie de message (ou un BMessage basé sur une constante command) à la destinataire de l'objet. L'appelant reste propriétaire du message. La fonction n'effectue son retour que lorsque le message a été délivré; Si vous envoyez un message (et non une constante command) vous pouvez positionner un délai de livraison en microseconde via deliveryTimeout.

Le destinataire peut répondre au message :

• Si vous fournissez une reply BMessage, la réponse est synchrone, dans un délai optionnel (replyTimeout) dont le décompte commence après que le message ait été délivré. Si la réponse ne parvient pas dans les délais, ou si le destinataire détruit le message original sans répondre, le reply–>what est positionné à B_NO_REPLY. L'appelant est responsable de l'allocation et de la libération de reply. message et reply peuvent être le même objet.

Soyez prudents lorque vous demandez une réponse synchrone : Si vous appellez SendMessage() à partir du thread du looper destinataire, vous provoquez un deadlock (ou, au mieux, un time out).

• Si vous fournissez un destinataire de réponse (replyMessenger ou replyHandler), la réponse est asynchrone, et est envoyée au destinataire de réponse.

• Si vous ne précisez ni message de réponse ni destinataire de réponse, la réponse du destinataire est envoyée au be_app_messenger.

CODES RETOUR

• B_OK. Le message a été délivré (et la réponse synchrone a été reçue, le cas échéant).

• B_TIMED_OUT. deliveryTimeout a expiré; le message n'a jamais atteint le destinataire.

• B_WOULD_BLOCK. Vous avez demandé un deliveryTimeout, et la file de messages du destinataire est pleine.

• B_BAD_PORT_ID. Le destinataire du messager est invalide, ou le port de réponse a été détruit durant l'attente d'une réponse (uniquement pour les demandes de réponses synchrones).

• B_NO_MORE_PORTS. Vous avez demandé une réponse synchrone, mais il n'y a plus de ports de réponse.

Si vous avez défini un handler en construisant votre BMessenger, et que ce handler a changé de looper depuis, SendMessage() ne délivrera pas son message, mais ne se plaindra pas (il retournera B_OK).

Target() , IsTargetLocal() , Team()

	BHandler *Target(BLooper **looper) const bool IsTargetLocal(void) const inline team_id Team(void) const

Target() retourne le handler de BMessenger (directement) and le looper (par référence dans looper). Cette fonction est applicable uniquement aux destinataires locaux. Si Target() retourne NULL, cela signifie un des quatre évènements suivants :

• Le destinataire est distant ; le looper est positionné à NULL.

• Le BMessenger n'a pas été initialisé ; le looper est positionné à NULL.

• Le handler est le handler favori du looper ; le looper sera valide.

• Le handler a été détruit ; le looper sera valide s'il n'a pas été également détruit.

IsTargetLocal() retourne true si le destinataire est local. Team() retourne un team de destinataire.

Team() voir Target()

Operateurs

= (assignation)

	BMessenger &operator =(const BMessenger&)

Assigne le destinataire BMessenger (à gauche) à l'objet (à droite).

== (égalité)

	bool operator ==(const BMessenger&) const

Deux BMessengers sont égaux s'ils ont le même destinataire.