doc-fr/reference/sam/functions/SAM-Message-header.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- EN-Revision: 1.6 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id='function.sammessage-header' xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>SAMMessage->header</refname>
  <refpurpose>Les propriétés d'en-tête d'un message</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <classsynopsis>
   <ooclass><classname>SAMMessage</classname></ooclass>
   <fieldsynopsis><type>object</type><varname>header</varname></fieldsynopsis>
  </classsynopsis>
  <para>
   La propriété <literal>header</literal> est un conteneur pour
   n'importe quel système ou propriétés utilisateur dont l'espace
   est associé au message.
  </para>
  <para>
   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.
  </para>
  <para>
   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".
  </para>
  <para>
   Les propriétés SAM définies sont les suivantes :
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Nom de la propriété</entry>
       <entry>Valeurs possibles</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>SAM_MESSAGEID</entry>
       <entry>
        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é.
       </entry>
      </row>
      <row>
       <entry>SAM_REPLY_TO</entry>
       <entry>
        Une chaîne de caractères fournissant l'identifiant de la file
        d'attente à laquelle les réponses à ce message doit être posté.
       </entry>
      </row>
      <row>
       <entry>SAM_TYPE</entry>
       <entry>
        <para>
         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.
        </para>
        <para>
         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.
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
  <para>
   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 :
  </para>
  <para>
   <example>
    <title>Définition d'une propriété au format texte en utilisant la syntaxe par défaut</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage();

$msg->header->myPropertyName = 'textData';
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   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 :
  </para>
  <para>
   <example>
    <title>Définition d'une propriété au format texte en utilisant un type</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage();

$msg->header->myPropertyName = array('textData', SAM_STRING);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Lorsque vous passez le type, il doit être un parmi les valeurs des
   constantes SAM définies, tel que dans le tableau suivant :
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Constante</entry>
       <entry>Description du type</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>SAM_BOOLEAN</entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry>SAM_BYTE</entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry>SAM_DOUBLE</entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry>SAM_FLOAT</entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry>SAM_INT</entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry>SAM_LONG</entry>
       <entry>
        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.
       </entry>
      </row>
      <row>
       <entry>SAM_STRING</entry>
       <entry>
        SAM interprétera la valeur spécifiée en tant que chaîne de caractères
        et la passera au système de messagerie.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Définition des propriétés en tant d'expéditeur d'un message</title>
    <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Récupération d'une valeurs depuis un message</title>
    <programlisting role="php">
<![CDATA[
<?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;

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="function.sammessage-body" /></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->