Les propriétés d'en-tête d'un message

# SAMMessage::header

(PECL sam >= 0.1.0)

SAMMessage::header — Les propriétés d'en-tête d'un message

### Description

object $SAMMessage->header;

La propriété header est un conteneur pour n'importe quel système ou propriétés utilisateur dont l'espace est associé au message.

Les propriétés peuvent être assignées par l'expéditeur du message pour contrôler la façon dont le gestionnaire de messagerie va le gérer ou peuvent être assignées par le système de messagerie lui-même pour communiquer au récepteur des informations additionnelles sur le message ou la façon dont il doit le gérer.

Quelques propriétés sont comprises par SAM dans le cas où les constantes y ont été définies. Cependant, la majorité des propriétés sont ignorées par l'implémentation de SAM et simplement passées aux systèmes de messagerie permettant ainsi à l'application d'utiliser les noms des propriétés spécifiques à la messagerie ou pour définir vos propres propriétés "utilisateur".

Les propriétés SAM définies sont les suivantes :

Nom de la propriété | Valeurs possibles
--- | ---
`SAM_MESSAGEID` | Lorsqu'un message est reçu, ce champs contient l'identifiant unique du message alloué par le système de messagerie. Lorsqu'un message est envoyé, ce champs est ignoré.
`SAM_REPLY_TO` | Une chaîne de caractères fournissant l'identifiant de la file d'attente à laquelle les réponses à ce message doit être posté.
`SAM_TYPE` | Une indication du type de message à envoyer. La valeur peut être `SAM_TEXT`, indiquant que le contenu du corps du message est du texte, ou `SAM_BYTES`, indiquant que le contenu du corps du message contient des formats définis. La façon dont cette propriété est utilisée dépend du serveur de messagerie. Pour le moment, un serveur de messagerie qui supporte les spécifications JMS (Java Message Service) interprète cette valeur et envoie des messages du type "jms_text" et "jms_bytes". De plus, si la propriété `SAM_TYPE` est définie à `SAM_TEXT`, les données fournies pour le corps du message est supposées être encodées UTF8.

Lors de la configuration des valeurs de ces propriétés, il est souvent utile de fournir un indice quant au format dans lequel la propriété doit être délivrée au serveur de messagerie. Par défaut, les valeurs des propriétés sont délivrées en tant que texte et la syntaxe simple suivante peut être utilisée pour définir une valeur :

Exemple #1 Définition d'une propriété au format texte en utilisant la syntaxe par défaut

`<?php
$msg = new SAMMessage();
$msg->header->myPropertyName = 'textData';
?>`

Si vous voulez passer une information sur le type, une syntaxe alternative peut être utilisée où la valeur et le type sont passés dans un tableau associatif :

Exemple #2 Définition d'une propriété au format texte en utilisant un type

`<?php
$msg = new SAMMessage();
$msg->header->myPropertyName = array('textData', SAM_STRING);
?>`

Lorsque vous passez le type, il doit être un parmi les valeurs des constantes SAM définies, tel que dans le tableau suivant :

Constante | Description du type
--- | ---
`SAM_BOOLEAN` | Toute valeur passée sera interprétée comme logique, `TRUE` ou `FALSE`. Si la valeur n'a pû être interprétée en tant qu'une valeur booléenne PHP, la valeur passée au système de messagerie sera indéfinie.
`SAM_BYTE` | Une valeur entière signée sur 8-bit. SAM tentera de convertir la valeur spécifiée en une valeur sur un octet à passer au système de messagerie. Si une chaîne de caractères est passée, on tentera de l'interpréter comme une valeur numérique. Si la valeur passée n'a pu être déterminée en tant que valeur binaire signé sur 8-bit, les données peuvent être perdues pendant la conversion.
`SAM_DOUBLE` | Une valeur longue, à virgule flottante. SAM tentera de convertir la valeur spécifiée en une valeur à virgule flottante avec 15 unités de précision à passer au système de messagerie. Si une chaîne de caractères est passée, on tentera de l'interpréter comme une valeur numérique. Si la valeur passée n'a pû être déterminée en tant que valeur à virgule flottante avec 15 unités de précision, les données peuvent être perdues pendant la conversion.
`SAM_FLOAT` | Une valeur courte, à virgule flottante. SAM tentera de convertir la valeur spécifiée en une valeur à virgule flottante avec 7 unités de précision à passer au système de messagerie. Si une chaîne de caractères est passée, on tentera de l'interpréter comme une valeur numérique. Si la valeur passée n'a pû être déterminée en tant que valeur à virgule flottante avec 7 unités de précision, les données peuvent être perdues pendant la conversion.
`SAM_INT` | Une valeur entière signée 32-bit. SAM tentera de convertir la valeur spécifiée en une valeur entière, signée 32-bit à passer au système de messagerie. Si une chaîne de caractères est passée, on tentera de l'interpréter comme une valeur numérique. Si la valeur passée n'a pu être déterminée en tant que valeur entière signée 32-bit, les données peuvent être perdues pendant la conversion.
`SAM_LONG` | Une valeur entière signée 64-bit. SAM tentera de convertir la valeur spécifiée en une valeur entière, signée 64-bit à passer au système de messagerie. Si une chaîne de caractères est passée, on tentera de l'interpréter comme une valeur numérique. Si la valeur passée n'a pû être déterminée en tant que valeur entière signée 64-bit, les données peuvent être perdues pendant la conversion.
`SAM_STRING` | SAM interprétera la valeur spécifiée en tant que chaîne de caractères et la passera au système de messagerie.

### Exemples

Exemple #3 Définition des propriétés en tant d'expéditeur d'un message

`<?php
$msg = new SAMMessage('Ceci est un message test');
// définisstion des propriétés spécifiques à SAM...
$msg->header->SAM_REPLY_TO = 'queue://test/replyQueue';
// définition des propriétés arbitraires...
//
// une chaîne par défaut
$msg->header->myStringProp1 = 'une chaîne';
// une chaîne avec un type
$msg->header->myStringProp2 = array('une autre chaîne', SAM_STRING);
// un booléen
$msg->header->myBoolProp = array(FALSE, SAM_BOOL);
// format numérique
$msg->header->myIntProp = array(32768, SAM_INT);
$msg->header->myLongProp = array(9876543, SAM_LONG);
$msg->header->myByteProp1 = array(123, SAM_BYTE);
$msg->header->myByteProp2 = array('12', SAM_BYTE);
$msg->header->myFloatProp = array(3.141592, SAM_FLOAT);
$msg->header->myDoubleProp = array(3.14159265358979, SAM_DOUBLE);
?>`

Exemple #4 Récupération d'une valeurs depuis un message

`<?php
// accès à une propriété spécifique
$intProp = $msg->header->MyIntProp;
// accès à une propriété spécifique
$encoding = $msg->header->JMS_IBM_Msgtype;
?>`

### Voir aussi

- SAMMessage::body