IMAP_MsgFetch

version 6.8.1

IMAP_MsgFetch (imap_ID; numéroMsg; donnéesMsg; valeursMsg) Entier

Paramètre	Type		Description
imap_ID	Entier long		Référence de connexion IMAP
numéroMsg	Entier long		Numéro du message
donnéesMsg	Texte		Elément(s) de données à récupérer
valeursMsg	Texte		Valeur(s) des données récupérées
Résultat	Entier		Code d'erreur

La commande IMAP_MsgFetch vous permet de récupérer un ou plusieurs éléments de données simples d'un message spécifique sans devoir le télécharger.

imap_ID contient la référence d'une session ouverte avec IMAP_Login.

Le paramètre numéroMsg désigne le message à examiner. Le numéroMsg représente la position du message dans la liste courante des messages. Attention, le numéroMsg d'un message n'est pas une valeur stable, il peut différer d'une session à l'autre.

Le paramètre donnéesMsg est une variable texte vous permettant de définir le ou les élément(s) de données que vous souhaitez récupérer. Si vous souhaitez définir plusieurs éléments de données, placez un espace entre chaque élément. Il existe deux sortes d'éléments de données :

• les éléments de données simples, récupérant une seule information,

• les macro éléments de données, récupérant plusieurs informations simples en une seule fois. Trois macros définissant des ensembles d'informations courants sont disponibles. Une macro doit être utilisée seule, c'est-à-dire sans autre macro ni élément de données.

Pour plus d'informations sur les éléments de données, reportez-vous plus loin aux paragraphes "Eléments de données simples" et "Macro éléments de données".

Le paramètre valeursMsg retourne soit une paire simple Elément de données/Valeur de données, soit une liste de paires Elément de données/Valeur de données.

• dans le premier cas, la structure du texte retourné est la suivante : Elément de données+Espace+Valeur de données

• dans le second cas, la structure du texte retourné est la suivante : Elément de données1+Espace+Valeur de données1+Espace+Elément de données2+Espace+Valeur de données2

valeursMsg peut contenir une liste entre parenthèses, une chaîne entre guillemets ou une chaîne simple, en fonction du paramètre donnéesMsg.

• Les listes entre parenthèses sont structurées de la manière suivante (voir l'exemple FLAGS) : (Valeur de données1+Espace+Valeur de données2). Des parenthèses vides sont retournées lorsqu'il n'y a aucune valeur de données. Cette règle ne s'applique pas aux listes d'adresses entre parenthèses (voir l'exemple ENVELOPE).

• Les chaînes entre guillemets sont structurées de la manière suivante (voir l'exemple INTERNALDATE) : Elément de données+Guillemets+Valeur de données+Guillemets. Lorsqu'une valeur de données est inexistante, une chaîne vide "" est retournée.

• Les chaînes simples (sans guillemets) indiquent des valeurs de type entier, entier long ou numérique et sont structurées de la manière suivante : Elément de données+Espace+Valeur de données. Dans ce cas, vous devrez généralement convertir les valeurs dans le type correspondant (voir l'exemple UID).

Note : Les guillemets sont utilisés lorsque les chaînes comportent des caractères spéciaux, tels que des espaces ou des parenthèses. Aussi, lors du traitement de la chaîne de caractères retournée par la commande IMAP_Fetch, les caractères guillemets sont pris en compte.

• INTERNALDATE

Récupère la date et l'heure internes du message sur le serveur IMAP. Il ne s'agit pas de la date et de l'heure de l'en-tête "Date", mais de la date et de l'heure indiquant le moment où le message a été reçu. Pour les messages envoyés via un serveur SMTP, cette information indique généralement la date et l'heure de la livraison finale du message. Pour les messages envoyés après la commande IMAP_Copy, cette information indique généralement la date et l'heure internes du message source.

L'élément de données INTERNALDATE retourne une chaîne entre guillemets.

   donnéesMsg:="INTERNALDATE"
   $Err:=IMAP_MsgFetch(imap_ID;1;donnéesMsg;valeursMsg) 

valeursMsg retourne INTERNALDATE "17-Jul-2001 15:45:37 +0200"

• FLAGS

Récupère entre parenthèses la liste des marqueurs définis pour le message. Les marqueurs sont séparés par des espaces.

   donnéesMsg:="FLAGS"
   $Err:=IMAP_MsgFetch(imap_ID;1;donnéesMsg;valeursMsg) 

valeursMsg retourne FLAGS () s'il n'y a aucun marqueur défini pour le message spécifié.

valeursMsg retourne FLAGS (\Seen \Answered) si les marqueurs \Seen et \Answered sont définis pour le message.

• RFC822.SIZE

Récupère le nombre d'octets du message, exprimé dans le format RFC-822. Le nom de l'élément de données est séparé de la valeur retournée par un espace. Une chaîne sans guillemets est retournée, ce qui signifie que vous devrez probablement la convertir en entier long (voir l'exemple UID).

   donnéesMsg:="RFC822.SIZE"
   $Err:=IMAP_MsgFetch(imap_ID;1;donnéesMsg;valeursMsg)

valeursMsg retourne RFC822.SIZE 99599

• ENVELOPE

Récupère entre parenthèses la liste décrivant la partie d'en-tête du message. Le serveur traite cette partie en analysant les champs d'en-tête et en leur fixant des valeurs par défaut si nécessaire.

Les champs d'en-tête sont retournés dans l'ordre suivant : date, objet, émetteur (from), expéditeur (sender), réponse à (reply-to), destinataire (to), copie (cc), copie discrète (bcc), en réponse à (in-reply-to) et message-id. Les champs date, objet, en réponse à et message-id sont des chaînes entre guillemets :

ENVELOPE ("date" "objet" (émetteur) (expéditeur) (réponse à) (destinataire) (copie) (copie discrète) "en réponse à" "message-id")

   donnéesMsg:="ENVELOPE"
   $Err:=IMAP_MsgFetch(imap_ID;1;donnéesMsg;valeursMsg)

valeursMsg retourne ENVELOPE ("Tue, 17 Jul 2001 17:26:34 +0200" "Test" (("RSmith" NIL "RSmith" "test")) (("RSmith" NIL "RSmith" "test")) (("RSmith" NIL "RSmith" "test")) (("RSmith" NIL "RSmith" "test")) () () "" "<ee6b33a.-1@Mail.x6foadRIbnm>")

Date :	"Tue, 17 Jul 2001 17:26:34 +0200"	En-tête date
Objet :	"Test"	En-tête objet
Emetteur :	(("RSmith" NIL "RSmith" "test"))	Structure d'adresse
Expéditeur :	(("RSmith" NIL "RSmith" "test"))	Structure d'adresse
Réponse à :	(("RSmith" NIL "RSmith" "test"))	Structure d'adresse
Destinataire :	(("RSmith" NIL "RSmith" "test"))	Structure d'adresse
Copie :	()	En-tête copie inutilisé
Copie discrète :	()	En-tête copie discrète inutilisé
En réponse à :	""	En-tête en réponse à inutilisé
Message-id :	"<ee6b33a.-1@Mail.x6foadRIbnm>"	En-tête message-id

Les en-têtes émetteur, expéditeur, réponse à, destinataire, copie et copie discrète sont des listes entre parenthèses de structures d'adresses. Une structure d'adresse est une liste décrivant une adresse de messagerie électronique. Les champs d'une structure d'adresse se présentent dans l'ordre suivant : nom, [SMTP] at-domain-list (source route), nom de la boîte aux lettres et nom de serveur. Par exemple, (("RSmith" NIL "RSmith" "test")).

• BODY

BODY retourne les mêmes informations que BODYSTRUCTURE excepté pour les données d'extension (voir BODYSTRUCTURE).

   donnéesMsg:="BODY"
   $Err:=IMAP_MsgFetch(imap_ID;1;donnéesMsg;valeursMsg)

valeursMsg retourne BODY ("TEXT" "PLAIN" ("CHARSET" "us-ascii") NIL NIL "8BIT" 8 1)

• BODYSTRUCTURE

Récupère la structure MIME du message. Le serveur traite cette partie en analysant les champs d'en-tête MIME dans l'en-tête et le corps du message. Cet élément de données est particulièrement utile pour analyser le contenu d'un message sans le télécharger. Par exemple, vous pouvez ainsi tester rapidement la taille de chaque partie ou le nom des fichiers joints. BODYSTRUCTURE retourne une liste entre parenthèses incluant des listes entre parenthèses, des chaînes entre guillemets et des chaînes sans guillemets.

En fonction du contenu du message, BODYSTRUCTURE retournera soit une liste "non-multipart" soit une liste imbriquée ("multipart") :

- Liste "non-multipart" entre parenthèses : semblable, par exemple, à un message électronique "non-multipart" ; la structure du corps d'un message texte simple de 48 lignes et 2279 octets peut être la suivante : ("TEXT" "PLAIN" ("CHARSET" "us-ascii") NIL NIL "8BIT" 8 1 NIL NIL NIL)

Les champs simples d'une liste "non-multipart" entre parenthèses apparaissent dans l'ordre suivant :

body type	Chaîne fournissant le type de contenu de media
	(Content-type: media type p. e. TEXT)
body subtype	Chaîne fournissant le sous-type de contenu de media
	(Content-type: sub type p. e. PLAIN)
body parameter	Liste entre parenthèses de paires attributs/valeurs
parenthesized list	[p. e. ("CHARSET" "US-ASCII" "NAME" "cc.diff") où "US-ASCII" est la
	valeur de "CHARSET" et "cc.diff" celle de "NAME".
body id	Chaîne fournissant le numéro d'ID du contenu (permet à un corps de
	faire référence à un autre). Ainsi, les corps de messages peuvent être
	référencés à l'aide du champ d'en-tête "Content-ID". Ce champ a une
	syntaxe particulière dans le cas d'un type de media
	multipart/alternative. Voir l'explication fournie dans la section de la
	RFC 2046 relative aux cas multipart/alternative.
body description	Chaîne décrivant le contenu
body encoding	Chaîne fournissant l'encodage de transfert du contenu
	(Content-Transfer-Encoding)
body size	Valeur numérique indiquant la taille du corps en octets. Notez que cette
	valeur concerne la taille pendant l'encodage de transfert et non la taille
	résultante après décodage.

Un corps de type MESSAGE de sous-type RFC822 contient, juste après les champs simples, la structure d'enveloppe, la structure de corps et la taille en lignes de texte du message encapsulé.

Un corps de type TEXT contient, juste après les champs simples, la taille en lignes de texte du corps. Notez que cette valeur concerne la taille pendant l'encodage et non la taille résultante après décodage.

Les données d'extension suivent les champs simples et les champs de type listés ci-dessus. Ces données ne sont jamais retournées avec l'élément BODY, mais le sont avec BODYSTRUCTURE.

Lorsqu'elles sont présentes, les données d'extension d'une liste "non-multipart" entre parenthèses doivent apparaître dans l'ordre suivant :

body MD5	Chaîne définissant la valeur MD5 du corps, comme défini dans [MD5]
body disposition	Liste entre parenthèses constituée d'une chaîne de type de disposition
	suivie d'une liste entre parenthèses de paires attributs/valeurs comme
	défini dans [DISPOSITION]
body language	Chaîne ou liste entre parenthèses indiquant le langage du corps comme
	défini dans [LANGUAGE-TAGS]

Description:

- Liste "multipart" entre parenthèses : c'est le cas de l'e-mail multipart ; elle inclut une liste "non-multipart" entre parenthèses.

Les parenthèses imbriquées indiquent des parties multiples (multiple parts). Le premier élément de la liste entre parenthèses est un corps imbriqué et non un type de corps. Le deuxième élément de la liste est le sous-type multipart (mixed, digest, parallel, alternative, etc.).

Le sous-type multipart est suivi des données d'extension.

Lorsqu'elles sont présentes, les données d'extension doivent apparaître dans l'ordre suivant :

body parameter	Liste entre parenthèses de paires attributs/valeurs
parenthesized list
body disposition	Liste entre parenthèses constituée d'une chaîne de type de disposition
	suivie d'une liste entre parenthèses de paires attributs/valeurs comme
	défini dans [DISPOSITION]
body language	Chaîne ou liste entre parenthèses indiquant le langage du corps comme
	défini dans [LANGUAGE-TAGS]

Les données d'extension ultérieures ne sont pas encore définies dans cette version du protocole. Ces données d'extension peuvent être constituées ou non de NIL(s), de chaînes, de nombres ou de listes entre parenthèses de ces données. Les implémentations clientes utilisant l'élément de donnée BODYSTRUCTURE doivent prévoir le traitement de ces données d'extension. Les implémentations Serveur ne doivent pas envoyer de telles données d'extension tant qu'elles ne sont pas définies dans une révision du protocole.

Description:

• UID

Récupère le numéro d'identification unique du message — équivaut à l'exécution de IMAP_UIDToMsgNum. Comme ce numéro est retourné dans une zone de texte, vous devrez le convertir en Entier long.

Exemple :

   donnéesMsg:="UID"
   $Err:=IMAP_MsgFetch(imap_ID;1;donnéesMsg;valeursMsg)

valeursMsg retourne UID 250000186

Pour obtenir un entier long :

   C_ENTIER LONG(vLongint)
   VLongint:=Num("250000186")

• FAST

Macro équivalente à : (FLAGS INTERNALDATE RFC822.SIZE)

   $Err:=IMAP_MsgFetch (imap_ID; msgNum;"FAST";valeursMsg)

valeursMsg retourne "FLAGS (\Seen \Answered) INTERNALDATE "17-Jul-2001 15:45:37 +0200" RFC822.SIZE 99599"

• ALL

Macro équivalente à : (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE)

• FULL

Macro équivalente à : (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODY)

IMAP_SetFlags, IMAP_UIDToMsgNum.