BMessage

Hérité de : aucun

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

Bibliothèque : libbe.so

Allocation : new, static, ou automatic

Résumé

Un BMessage est un paquet d'informations structurées. Chaque BMessage contient une constante commande et un certain nombre de champs de données.

• La constante commande est une valeur int32 qui décrit, grossièrement, l'objet du BMessage. Elle est stockée en tant que membre de données public what. Vous valorisez et examinez toujours la valeur what directement — inutile d'appeler une fonction. (Vous pouvez valoriser facilement la constante commande à la création de votre objet BMessage.)
• Les champs de données sont des triplets nom/type/valeur. Un champ est identifié en premier lieu par son nom, mais vous pouvez rechercher des champs par leur nom, leur type, ou une combinaison des deux. Le type est codé comme une constante ( B_INT32_TYPE, B_STRING_TYPE, etc. ), et a pour objet de décrire le type de valeur contenue dans le champ. Un champ ne peut avoir qu'un nom et qu'un type, mais peut contenir un tableau de valeurs. Les valeurs individuelles du champ sont accessibles via un index.

Ni la constante commande ni les champs de données ne sont obligatoires. Vous pouvez créer un BMessage avec des données mais sans commande, ou qui possède seulement une commande. Bien entendu, créer un BMessage qui n'a ni l'un ni l'autre est sans intérêt.

A lire au préalable

Les BMessages sont utilisés partout dans les kits pour envoyer des données (ou des notifications) à un autre thread — éventuellement dans une autre application. Pour comprendre comment les BMessages s'inscrivent dans le système de messagerie, voir "Messagerie".

La classe BMessage participe également à nombre de fonctions qui aident à définir le système des scripts. Voir "Scripts" pour une introduction à ce système.

Les BMessages sont aussi utilisés par nombre de classes (BClipboard, BArchivable, et autres) pour leur capacité à stocker des données.

Types de fonctions

La classe BMessage définit cinq types de fonctions :

• Fonctions de champ de données. Ces fonctions affectent ou retrouvent la valeur d'un champ de données. Voir AddData(), FindData(), ReplaceData(), et RemoveName().
• Fonctions Info. Ces fonctions retrouvent des informations sur l'état et les contenus de BMessage. Voir IsSystem() et GetInfo().
• Fonctions de messagerie. Ces fonctions font partie du système de messagerie. Un petit ensemble de fonctions informe du statut d'un message reçu. Par exemple, IsSourceWaiting() indique si l'émetteur du message attend une réponse, WasDropped() informe s'il a été glissé-déposé, et DropPoint() précise où il a été déposé. SendReply()
• Fonctions de scripts, comme AddSpecifier() et PopSpecifier().
• Fonctions de mise à plat. Les données d'un BMessage peuvent être mises à plat. Voir Flatten().

Le propriétaire du BMessage

La documentation des fonctions qui acceptent ou renvoient un objet BMessage vous indique qui prend en charge la destruction de l'objet. La plupart des fonctions acceptant un paramètre BMessage copient l'objet, laissant à l'appelant la responsabilité de détruire le paramètre. Les exceptions — c.a.d. les fonctions acceptant les BMessages et devenant propriétaires de l'objet — sont listées plus bas.

Les fonctions qui renvoient un BMessage en restent généralement les propriétaires ; en général, vous ne détruisez pas les BMessages qui vous sont passés. Les exceptions — les fonctions qui s'attendent à ce que l'appelant devienne propriétaire du BMessage passé — sont listés plus bas.

Données Membres

uint32 what   
Une constante programmée qui capture l'objet du message.

Constructeur et Destructeur

BMessage()

Crée un nouvel objet BMessage qui possède une constante command donnée, ou qui est la copie d'un autre BMessage. S'il est une copie, le nouvel objet contient la même constante de commande et les mêmes champs de données que message.

voir aussi : BLooper::DetachCurrentMessage()

~BMessage()

Libère toute la mémoire allouée pour les données du message. Si l'expéditeur du message attend une réponse et n'en a pas reçue, une réponse par défaut (avec la donnée membre B_NO_REPLY en tant que donnée membre what) est envoyée avant destruction du message.

Le système reste propriétaire des messages qu'il vous délivre. Chaque boucle de message détruit normalement les BMessages délivrés, une fois que l'application a fini d'y répondre.

Fonctions Membres

AddData() , AddBool() , AddInt8() , AddInt16() , AddInt32() , AddInt64() , AddFloat() , AddDouble() , AddString() , AddPoint() , AddRect() , AddRef() , AddMessage() ,
AddMessenger() , AddPointer() , AddFlat()

Ces fonctions ajoutent des données au champ nommé name et assignent un type de données au champ. Le nom des champs ne peut dépasser 255 caractères. Si plus d'un élément de données est ajouté sous le même nom, le BMessage crée un tableau de données pour ce nom. Chaque fois que vous ajoutez une autre valeur (sous le même nom), cette valeur est ajoutée en fin de tableau — vous ne pouvez pas ajouter de valeur à un index spécifié. Un champ donné ne peut stocker qu'un type de données.

AddData() copie numBytes de data dans le champ, et effecte à la donnée un code type. Elle copie tout ce que le pointeur de data référence. Par exemple, si vous voulez ajouter une chaîne de caractères au message, data doit être le pointeur de chaînes (char *). Si vous souhaitez ajouter le pointeur lui-même, et non les caractères, data doit être un pointeur sur le pointeur (char **). Le type assigné doit être un type de données spécifique ; il ne peut pas être B_ANY_TYPE.

Lorsque vous appelez AddData() pour placer le premier élément d'un tableau sous un nouveau nom, vous pouvez lui fournir deux paramètres, fixedSize et numItems, ce qui améliorera l'efficacité de l'objet. Si l'indicateur fixedSize est à true, chaque élément du tableau doit avoir le même nombre d'octets ; si l'indicateur est à false, les éléments peuvent être de taille variable. numItems indique à l'objet de pré-allouer de la mémoire pour un certain nombre d'éléments. Ce n'est pas limitatif - vous pouvez ajouter plus de numItems au champ.

La plupart des autres fonctions sont des variantes de AddData() qui codent en dur le type des champs. Par exemple, AddFloat() effecte le type B_FLOAT_TYPE ; AddBool() effecte B_BOOL_TYPE, etc.

AddString(), comme AddData(), utilise un pointeur sur les données qu'elle ajoute, ou vous pouvez utiliser un objet BString. La chaîne doit être terminée par null ; le caractère null est compté et copié dans le message. Similairement, AddRef() ajoute la cible pointée à la structure entry_ref du message (et le nom de longueur variable qui est un des éléments de la structure) ; AddMessage() ajoute un BMessage à un autre.

Les données sont directement et simplement passées aux autres fonctions. Par exemple, AddInt32() accepte un int32 ou un uint32 et AddMessenger() accepte un objet BMessenger, alors que AddData() aurait utilisé un pointeur sur un int32 et un pointeur sur un BMessenger. AddPointer() ajoute seulement le pointeur qu'on lui passe, et non les données pointées. Pour faire la même chose, AddData() veut un pointeur sur le pointeur. (Le pointeur n'est valide que localement ; il est inutilisable pour une destination éloignée.)

AddFlat() met à plat un object (en appelant sa fonction Flatten()) et ajoute au message les données à plat. Elle appelle la fonction TypeCode() de l'objet, pour connaitre le code du type à associer aux données. Les objets ajoutés via AddFlat()doivent dériver de BFlattenable (définie dans le kit de support).

Vous pouvez également fournir une indication numItems à AddFlat() quand vous l'appelez pour bâtir un nouveau tableau. AddFlat() appelle la fonction IsFixedSize() de l'objet pour découvrir si tous les éléments du tableau sont de même taille.

Ces fonctions retournent B_ERROR si les données sont trop volumineuses pour être ajoutées au message, B_BAD_TYPE si la donnée est du mauvais type pour être ajoutée à un tableau existant, B_NO_MEMORY si le BMessage ne peut acquérir assez de mémoire pour stocker les données, et B_BAD_VALUE si le name proposé pour les données dépasse 255 octets. Si tout va bien, elles retournent B_OK.

Il n'y a pas de limite au nombre de champs nommés qu'un message peut contenir ou à la taille d'un champ de données. Néanmoins, comme la recherche est linéaire, éplucher une très longue liste de noms pour trouver un élément de données particulier peut être inefficace. De même, à cause de la masse de données devant être déplacée, un message très volumineux peut ralentir le mécanisme de délivrance. Il est parfois plus intéressant de stocker une partie des informations dans un emplacement commun (fichier, presse-papier privé, zone de mémoire partagée) et d'y faire simplement référence dans le message.

voir aussi : FindData(), GetInfo()

AddSpecifier()

Ajoute un "spécifieur" (specifier) à la pile des spécifieurs. Il existe plusieurs variantes de cette méthode. Le première ajoute le spécifieur message à la pile des spécifieurs. Les autres méthodes ajoute un spécifieur ciblant la propriété property, avec respectivement les constantes de spécifieur suivantes : B_DIRECT_SPECIFIER, B_INDEX_SPECIFIER, B_RANGE_SPECIFIER, et B_NAME_SPECIFIER. Pour tous les autres spécifieurs, vous devez construire séparément le spécifieur, puis appeler ensuite AddSpecifier() pour le message. Pour plus de détails sur les spécifieurs, voir la section "Scripts" mentionnée en début de chapitre.

Les spécifieurs sont stockés dans un tableau de données nommé "specifiers." Toutefois, comme AddSpecifier() définit aussi la notion de spécifieur courant, les spécifieurs devraient toujours être ajoutés à un message de scripts avec cette méthode plutôt qu'avec AddMessage().

AddSpecifier() retourne B_OK si elle a été capable d'ajouter le spécifieur au BMessage ou un code erreur, généralement uniquement B_NO_MEMORY, pour indiquer l'épuisement de la mémoire dans le cas contraire.

voir aussi : GetCurrentSpecifier(), HasSpecifiers(), PopSpecifier()

CountNames()

Retourne le nombre de champs de données nommés dans le BMessage stockant des données du type spécifié. Un tableau de données sous un seul nom compte pour un seul champ ; chaque nom n'est compté qu'une fois, quelque soit le nombre d'éléments de données stockés sous ce nom.

Si le type est B_ANY_TYPE, cette fonction compte tous les champs nommés. Si le type est un type explicite, elle ne compte que les champs stockant les données enregistrées dans ce type.

voir aussi : GetInfo()

DropPoint() voir WasDropped()

FindData(), FindBool(), FintInt8(), FindInt16(), FindInt32(), FindInt64(), FindFloat(),
FindDouble(), FindString(), FindPoint(), FindRect(), FindRef(), FindMessage(),
FindMessenger(), FindPointer(), FindFlat()

Ces fonctions retrouvent les données des BMessages. Chacune recherche les données stockées sous le name spécifié. Si plus d'un élément de données porte le même nom, un index peut être fourni pour indiquer à la fonction quel élément doit être retrouvé dans le tableau name. Les indices débutent à 0. Si un index n'est pas fourni, la fonction retrouve le premier, ou l'unique, élément du tableau.

Dans tous les cas, sauf FindData() et FindString(), les données retrouvées du BMessage sont copiées dans le paramètre en référence ; l'appelant est responsable de la libération des données copiées. Pour FindData() et la version non BString de FindString(), un pointeur vers les données est retourné ; le BMessage conserve la propriété des données présentes et les détruit quand l'objet est lui-même détruit.

FindData() place, dans *data, un pointeur sur l'élément de données demandé. La taille, en octets, de l'élément est écrite dans numBytes. Si le type est B_ANY_TYPE, elle fournit un pointeur sur les données quelque soit leur type. Mais si le type est un type de données explicite, elle ne fournit un pointeur que si le champ name contient des données de ce type.

Les autres fonctions sont des versions spécialisées de FindData(). Elles correspondent aux fonctions concernées Add...() et recherchent les données nommées pour un type spécificique, comme décrit ci-dessous :

Ces autres fonctions spécialisées par type retrouvent les éléments de données demandés du message en les copiant dans la variable référencée dans le dernier paramètre ; vous obtenez les données, et non un pointeur sur elles. Par exemple, FindMessenger() affecte le BMessenger retrouvé dans le message à l'objet messenger, alors que FindData() fournit seulement un pointeur sur le BMessenger. FindPointer() place le pointeur trouvé dans la variable void* que pointer référence ; FindData(), comme illustré plus haut, fournit un pointeur sur le pointeur. (Si le message a été délivré en provenance d'une source distante, les pointeurs trouvés ne sont pas valides.)

FindRef() retrouve une structure entry_ref ; les données utilisées pour reconstituer la structure peuvent avoir été ajoutées comme une entry_ref (via AddRef()), ou comme un objet BPath mis à plat ( AddFlat()).

FindFlat() affecte l'objet stocké dans le BMessage à l'object passé en paramètre — elle appelle la fonction Unflatten() de l'object et lui passe les données mises à plat du message — du moment que les deux objets sont de type compatible. Le paramètre objet de la fonction AllowsTypeCode() doit renvoyer true quand elle est testée avec le type stocké dans le message ; sinon, FindFlat() échoue et renvoie B_BAD_VALUE.

Si ces fonctions ne peuvent trouver de données associées à un name, elles renvoient une erreur B_NAME_NOT_FOUND. Si elles ne peuvent trouver des données name du type demandé (ou du type que la fonction retourne), elles renvoient B_BAD_TYPE. Si l'index est en dehors des bornes, elles renvoient B_BAD_INDEX. Vous ne pouvez vous fier aux données trouvées que si elles renvoient B_OK et si les données ont été correctement enregistrées lors de leur ajout au message.

Quand elles échouent, FindData() et FindString() fournissent des pointeurs NULL. FindRect() vous restitue un rectangle non valide et FindMessenger() un BMessenger invalide. La plupart des autres fonctions positionnent les données à 0, ce qui peut être confondu avec des valeurs valides.

Retrouver un élément de donnée ne l'ôte pas du BMessage.

(Plusieurs fonctions, telles que FindRect() et FindInt32(), possèdent des versions qui ramènent directement la valeur trouvée. Ces versions ne retournent pas les erreurs et ne seront peut-être pas maintenues dans le futur.)

voir aussi : GetInfo(), AddData()

Flatten() , Unflatten() , FlattenedSize()

Ces fonctions écrivent un BMessage et les données qu'il contient dans un tampon "plat" (sans type) d'octets, ou reconstruisent un objet BMessage à partir d'un tel tampon.

Si on lui passe un object BDataIO (incluant un BFile), Flatten() appelle la fonction Write() de l'objet pour écrire les données du message. Si on lui passe l'address d'un tampon, elle commence à écrire au début du tampon.
FlattenedSize() retourne le nombre d'octets nécessaires au tampon pour contenir l'objet mis à plat. Flatten() place le nombre d'octets réellement écrits dans la variable référencée par son paramètre numBytes.

Unflatten() vide le BMessage de toute information qu'il peut contenir, puis initialise l'objet à partir des données lues dans le tampon. Si on lui passe un object BDataIO, elle appelle la fonction Read() de l'objet pour lire les données du message. Si on lui passe l'address d'un tampon, elle commence la lecture au début du tampon. Il revient à l'appelant de s'assurer que Unflatten() lise les données que Flatten() a écrit et que les pointeurs sont correctement positionnés.

Flatten() renvoie toutes les erreurs rencontrées lors de l'écriture des données, ou B_OK s'il n'y a pas d'erreur.

Si elle ne reconnait pas les données du tampon comme étant un objet mis à plat ou s'il y a un incident en lisant les données, Unflatten() renvoie B_BAD_VALUE. Si elle n'a pas suffisament de mémoire pour recréer la totalité du message, elle renvoie B_NO_MEMORY. Sinon, elle renvoie B_OK.

voir aussi : la classe BDataIO dans le kit de support.

GetCurrentSpecifier() , PopSpecifier()

GetCurrentSpecifier() récupère le spécifieur courant du BMessage, celui au sommet de la pile de spécifieurs ; PopSpecifier() modifie la notion de spécifieur courant, en dépilant le spécifieur courant de la pile.

Ces fonctions aident à la mise en oeuvre d'une version de classe spécifique de la fonction ResolveSpecifier() de BHandler — la première récupère le spécifieur à résoudre, et la seconde le dépile après sa résolution. Vous pouvez également les appeler pour examiner les spécifieurs concernés lorsque vous manipulez un message ciblant une propriété objet (comme B_GET_PROPERTY).

Un BMessage de scripts conserve les spécifieurs dans un tableau de données nommé "specifiers" ; chaque spécifieur est lui-même un BMessage, mais qui possède une structure spéciale et une utilité spécifique dans le système de scripts. Voir la section "Scripts" mentionnée en début de chapitre pour une présentation du système et du rôle des spécifieurs.

Les spécifieurs d'un message sont ordonnés et, jusqu' à ce que PopSpecifier() soit appelée, le dernier ajouté — le plus élevé dans l'index — est le spécifieur courant. PopSpecifier() décrémente simplement l'index qui donne le spécifieur courant ; elle ne supprime rien du BMessage.

GetCurrentSpecifier() place l'index du spécifieur courant dans la variable que référence son premier paramètre, index. Si d'autres paramètres sont fournis, elle fait du specifier du BMessage une copie du spécifieur courant. Elle extrait également deux éléments d'information du specifier : elle place le membre de données what du spécifieur dans la variable what et un pointeur sur le nom de la propriété dans la variable property. Ces deux derniers paramètres en sortie ne seront pas valides si le paramètre specifier est NULL.

Ces deux fonctions échouent si le BMessage ne contient pas de spécifieurs. En plus, GetCurrentSpecifier() échoue si elle ne peut trouver de données dans le BMessage pour ses paramètres specifier et property, et PopSpecifier() échoue si le BMessage n'est celui qui vous a été délivré après avoir été traité via une boucle de message. Lorqu'elles échouent, GetCurrentSpecifier() renvoie B_BAD_SCRIPT_SYNTAX, et PopSpecifier() renvoie B_BAD_VALUE. En cas de succès, ces deux fonctions renvoient B_OK.

voir aussi : AddSpecifier(), HasSpecifiers(), BHandler::ResolveSpecifier()

GetInfo()

Fournit des informations sur les champs de données stockés dans le BMessage.

Quand on lui passe un name qui correspond à un nom du BMessage, GetInfo() place le type de la donnée stockée sous ce nom dans la variable référencée par typeFound et écrit le nombre d'éléments de données dans la variable référencée par countFound. Elle renvoie ensuite B_OK. Si elle ne peut retrouver le champ name dans le BMessage, elle positionne la variable countFound à 0, et renvoie B_NAME_NOT_FOUND (sans modifier la variable typeFound).

Lorsque le paramètre fixedSize est précisé, le booléen référencé par fixedSize vaut true si tous les éléments du tableau nommé doivent avoir la même taille, et false si les éléments peuvent être de taille différente (voir AddData()).

Quand on lui passe un type et un index, GetInfo() regarde simplement les champs qui stockent les données du type demandé et fournit des informations sur le champ présent à l'index demandé. Les indices commencent à 0 et sont sensibles au type. Par exemple, si le type demandé est B_DOUBLE_TYPE et que le BMessage contient un total de trois champs nommés stockant des données double, le premier champ sera à l'index 0, le deuxième à 1, et le troisième à 2 — peu importe quels autres types de données les séparent dans le BMessage, et peu importe le nombre d'éléments que chaque champ contient. (Notez que dans ce cas, l'index s'applique aux champs, chacun d'un nom différent, et non aux éléments de données de chaque champ particulier.) Si le type demandé est B_ANY_TYPE, cette fonction recherche tous les champs et obtient les informations sur ceux à l'index demandé, quelque soit leur type.

Si la donnée du type demandé à l'index indiqué est bien retrouvée, GetInfo() renvoie B_OK et fournit des informations sur la donnée via ses trois derniers paramètres :

• Elle place un pointeur sur le nom du champ de donnée dans la variable référencée par nameFound.
• Elle donne le code du type de données que le champ contient dans la variable désignée par typeFound. Celui-ci est le même que le type demandé, sauf si ce dernier est B_ANY_TYPE, et dans ce cas typeFound contient le type réellement stocké sous le nom de la donnée.
• Elle enregistre le nombre d'éléments de données stockés dans le champ dans la variable référencée par countFound.

Si GetInfo() ne peut trouver de données du type demandé à l'index indiqué, elle affecte 0 à la variable countFound, et renvoie B_BAD_TYPE. Si l'index est en dehors des bornes, elle renvoie B_BAD_INDEX.

Cette version de GetInfo() peut servir à itérer les données du BMessage. Par exemple :

   char  *name;
   uint32  type;
   int32   count;
   
   for ( int32 i = 0; 
         msg->GetInfo(B_ANY_TYPE, i, &name, &type, &count) == B_OK;
         i++ ) {
       . . .
   }

Si l'index est incrémenté de cette manière, à partir de 0, toutes les données du type demandé auront été lues lorsque GetInfo() renverra B_NAME_NOT_FOUND. Si le type demandé est B_ANY_TYPE, comme dans l'exemple ci-dessus, on retrouvera le nom et le type de chaque champ du BMessage.

voir aussi : HasData(), AddData(), FindData()

HasSpecifiers()

Renvoie true si le BMessage a des spécifieurs ajoutés via une fonction AddSpecifier(), et false dans le cas contraire.

voir aussi : AddSpecifier(), GetCurrentSpecifier()

IsEmpty() voir MakeEmpty()

IsReply() voir WasDelivered()

IsSourceRemote() voir WasDelivered()

IsSourceWaiting() voir WasDelivered()

IsSystem()

Renvoie true si le membre donnée what de l'objet BMessage identifie ce dernier comme un message système, et false dans le cas contraire.

MakeEmpty() , IsEmpty()

MakeEmpty() ôte et libère toutes les données ajoutées au BMessage, sans altérer la constante what. Elle renvoie B_OK, sauf si le message ne peut être modifié (c'est le cas s'il a été déplacé par glisser-déposer), elle renvoie alors B_ERROR.

IsEmpty() renvoie true si le BMessage ne possède pas de données (vidées ou non par MakeEmpty()), et false s'il en contient.

voir aussi : RemoveName()

Previous() voir WasDelivered()

PrintToStream()

Imprime des informations au sujet du BMessage sur le flux de sortie standard - standard output stream - (stdout). Chaque champ de données nommées est édité au format suivant,

   #entry name, type = type, count = count

où name est le nom sous lequel la donnée est enregistrée, type est la constante indiquant de quel type de données il s'agit, et count est le nombre d'éléments de données du tableau nommé.

RemoveName() , RemoveData()

RemoveName() ôte toutes les données entrées dans le BMessage sous name et le nom lui-même. RemoveData() ôte un seul élément de données à l' index du tableau name. Si le tableau ne contient qu'un élément, elle supprime le tableau et le nom, comme le ferait RemoveName().

Les deux fonctions libèrent la mémoire allouée aux données, et renvoient B_OK en cas de succès. Néanmoins, si aucune donnée du BMessage ne porte le nom name, elles renvoient une erreur B_NAME_NOT_FOUND. Si les données du message peuvent être lues mais non modifiées (c'est le cas s'il a été déplacé par glisser-déposer), elles renvoient toutes deux B_ERROR. Si l'index est en dehors des bornes, RemoveData() renvoie B_BAD_INDEX (l'index est trop élevé) ou B_BAD_VALUE (la valeur passée est un nombre négatif).

voir aussi : MakeEmpty()

ReplaceData() , ReplaceBool() , ReplaceInt8() , ReplaceInt16() , ReplaceInt32() , ReplaceInt64() , ReplaceFloat() , ReplaceDouble() , ReplaceString() , ReplacePoint() , ReplaceRect() ,
ReplaceRef() , ReplaceMessage() , ReplaceMessenger() , ReplacePointer() , ReplaceFlat()

Ces fonctions remplacent un élément de données dans le champ name par un autre élément passé en paramètre. Si un index est fourni, elles remplacent l'élément du tableau name à cet index ; si aucun index n'est précisé, elles remplacent le premier (ou l'unique) élément stocké sous name. Si un index est précisé mais en dehors des bornes, le remplacement échoue.

ReplaceData() remplace un élément du champ name avec numBytes de data, mais uniquement si le type spécifié pour la donnée correspond au type réel de la donnée stockée dans le champ. Le type doit être explicite ; ce ne peut être B_ANY_TYPE.

FindFlat() remplace un objet mis à plat par un autre object, à la condition que le type indiqué par le paramètre object (par sa fonction TypeCode()) corresponde au type enregistré pour l'élément dans le message. Dans le cas contraire, elle renvoie B_BAD_VALUE.

Les autres fonctions sont des versions simplifiées de ReplaceData(). Chacune gère le type spécifique de données déclaré dans leur dernier paramètre. Elles réussissent si ce type correspond au type réel de la donnée stockée dans le champ name, et échouent dans le cas contraire. La nouvelle donnée est ajoutée exactement comme le spécifie la fonction concernée
Add...().

En cas de succès, toutes ces fonctions renvoient B_OK. En cas d'échec, elles renvoient un code erreur - B_ERROR si le message est en lecture seule (comme c'est le cas quand le message est en train d'être déplacé par glisser-déposer), B_BAD_INDEX si l'index est en dehors des bornes, B_NAME_NOT_FOUND si le champ name n'existe pas, et B_BAD_TYPE si le champ ne contient pas de données du type indiqué.

voir aussi : AddData()

ReturnAddress()

Renvoie un objet BMessenger qui peut être utilisé pour répondre au BMessage. Appeler la fonction SendMessage() de BMessenger équivaut à appeler SendReply(), sauf que le message de retour ne sera pas marqué en tant que réponse. Si une réponse n'est pas permise (le BMessage n'a pas été délivré), le BMessenger retourné est invalide.

Si vous voulez utiliser ReturnAddress() BMessenger pour envoyer une réponse synchrone, vous devrez le faire avant que le BMessage soit détruit et qu'une réponse par défaut soit envoyée.

voir aussi : SendReply(), WasDelivered()

SendReply()

Envoie une réponse message à l'émetteur du BMessage (dans le cas d'une réponse synchrone) ou à une cible BHandler (dans le cas d'une réponse asynchrone). Le fait que la réponse soit synchrone ou asynchrone dépend de comment le BMessage qui envoie la réponse a lui-même été envoyé :

• La réponse est synchrone si l'émetteur du message est en attente d'une réponse. La fonction qui a envoyé le BMessage n'effectue pas son retour avant d'avoir reçue la réponse (ou qu'un délai expire). Si la réponse attendue n'a pas été envoyé au moment ou l'objet BMessage est détruit, un message par défaut B_NO_REPLY est renvoyé à l'émetteur. Si une réponse est envoyée après que l'émetteur ait cessé d'attendre, la réponse message disparait dans les entrailles du système.
• La réponse est asynchrone si l'émetteur du message n'est pas en attente d'une réponse. Dans ce cas, la fonction émettrice désigne un destinataire BHandler et BLooper pour toute réponse qui pourrait être envoyée, puis effectue immédiatement son retour après avoir injecté le BMessage dans le tuyau. Les messages postés et les messages qui sont glissés-déposés sont également éligibles pour des réponses asynchrones.

SendReply() fonctionne uniquement pour les objets BMessage ayant été traités par une boucle de message et délivrés. L'appelant conserve la propriété de la réponse message passée à SendReply(); elle peut être détruite (ou laissée mourir sur la pile) après le retour de la fonction.

SendReply() envoie un message — un message de réponse, pour être exact, mais néanmoins un message. Elle se comporte exactement comme l'autre fonction émettrice de message, SendMessage() de BMessenger :

• En lui passant un paramètre reply, vous pouvez demander une réponse synchrone au message de réponse qu'elle émet. Elle n'effectuera pas son retour avant d'avoir reçu la réponse.
• En fournissant un paramètre replyHandler, vous pouvez mettre en place une réponse asynchrone. Si un destinataire explicite n'est pas spécifié, l'objet BApplication prend en charge la réponse, s'il en existe une.

Par défaut, SendReply() n'effectue son retour que lorsque le message de réponse est délivré (placé dans la file d'attente du port du BLooper). Il est possible, dans certaines circonstances, que la file d'attente du port de réception soit pleine, alors SendReply() se bloque jusqu'à ce qu'un emplacement se libère. Toutefois, vous pouvez limiter la durée pendant laquelle SendReply() attend pour délivrer le message avant d'abandonner et d'effectuer son retour. Le paramètre sendTimeout représente le nombre de microsecondes accordé à la fonction pour effectuer sa tâche. Si le temps limite est dépassé, la fonction échoue et renvoie une erreur ( B_TIMED_OUT ).

Lorsqu'on demande une réponse synchrone, des limites distinctes sendTimeout et replyTimeout peuvent être définies pour l'envoi du message et la réception de la réponse. Il n'y a aucune limite de temps si la valeur de timeout est spécifiée à B_INFINITE_TIMEOUT — comme elle l'est par défaut. la fonction ne bloquera pas du tout si le timeout est fixé à 0.

Si une command est passée plutôt qu'un message, SendReply() construit la réponse BMessage, initialise son membre données what avec la constante command, et l'envoie comme n'importe quelle autre réponse. Les versions command de cette fonction possèdent des timeouts infinis ; elles bloquent jusqu'à ce que le message soit délivré et, si demandé, qu'une réponse synchrone soit reçue.

Cette fonction renvoie B_OK si la réponse est envoyée avec succès. S'il y a un problème lors de l'envoi du message, elle renvoie la même sorte de code erreur que SendMessage() de BMessenger. Elle peut également restituer un problème de réponse spécifique. Les valeurs de retour les plus significatives sont les suivantes :

Si vous voulez introduire un délai dans l'envoi d'une réponse et conserver l'objet BMessage au-delà du temps imparti pour sa destruction, vous avez la possibilité de le détacher de la boucle de message. Voir DetachCurrentMessage() dans la classe BLooper.

voir aussi : BMessenger::SendMessage(), BLooper::DetachCurrentMessage(), Error, ReturnAddress()

Unflatten() voir Flatten()

WasDelivered() , IsSourceRemote() , IsSourceWaiting() , IsReply() , Previous()

Ces fonctions peuvent vous aider si vous êtes impliqué dans un échange de messages ou si vous êtes en train de gérer une communication en cours.

WasDelivered() indique s'il est possible d'envoyer une réponse à un message. Elle renvoie true si le BMessage a été posté, envoyé, ou déposé — c'est à dire un message qui a été pris en charge par une boucle de message — et false si le message n'a pas encore été délivré, quelque soit la méthode concernée.

IsSourceRemote() renvoie true si le message a sa source dans une autre application, et false si la source est locale ou si le message n'a pas encore été délivré.

IsSourceWaiting() renvoie true si la source du message attend une réponse synchrone, et false dans le cas contraire. Le thread source peut demander et attendre une réponse quand il appelle soit la fonction SendMessage() de BMessenger soit la fonction SendReply() de BMessage.

IsReply() renvoie true si le BMessage est une réponse à un précédent message (s'il a été envoyé par la fonction SendReply()), et false dans le cas contraire.

Previous() renvoie le message précédent — celui pour lequel le BMessage en cours est une réponse. Elle fonctionne seulement pour un BMessage ayant reçu une réponse asynchrone d'un précédent message. Une réponse synchrone est reçue dans le contexte du message précédent, donc il n'est pas nécessaire d'appeler une fonction pour la récupérer. Mais quand une réponse asynchrone est reçue, le contexte du message d'origine est perdu ; cette fonction peut le restituer. Previous() renvoie NULL si le BMessage n'est pas une réponse asynchrone à un autre message.

voir aussi : BMessenger::SendMessage(), SendReply(), ReturnAddress()

WasDropped() , DropPoint()

WasDropped() renvoie true si l'utilisateur a délivré le BMessage par glisser-déposer, et false si le message a été posté ou émis par une application ou s'il n'a pas encore été délivré.

DropPoint() donne l'emplacement du curseur au moment où le message a été déposé (à l'instant ou l'utilisateur a relaché le bouton de la souris). Elle renvoie directement les coordonnées écran du point et, si un paramètre offset est fourni, le renvoie en référence à des coordonnées basées sur l'image ou le rectangle que l'utilisateur a déplacé. L'offset se réfère au système de coordonnées définissant (0.0, 0.0) comme le coin supérieur gauche du rectangle ou de l'image déplacé.

Comme n'importe quelle valeur peut être une coordonnée valide, DropPoint() produit des résultats valables uniquement si WasDropped() renvoie true.

voir aussi : BView::DragMessage()

Opérateurs

= (affectation)

Affecte un objet BMessage à un autre. Après l'affectation, les deux objets sont des duplicata l'un de l'autre, sans données partagées.

new

Alloue de la mémoire pour un objet BMessage, ou prend la mémoire à partir d'un cache alloué préalablement. Le mécanisme de cache est un moyen efficace de gérer la mémoire pour des objets qui sont créés fréquemment et utilisés pour de courtes périodes de temps, comme les BMessages le sont typiquement.

delete

Libère la mémoire allouée par la version BMessage de new, ce qui peut signifier la restauration de la mémoire du cache.