4D Doc Center : IMAP

4D Internet Commands v14

IMAP_ListMBs


IMAP_ListMBs ( imap_ID ; réfBL ; nomBL ; tabNomsBL ; tabAttribsBL ; tabHiérarBL ; abonnementsBL ) -> Résultat

Paramètre	Type	Description
imap_ID	Entier long	Référence de connexion IMAP
réfBL	Texte	Chaîne vide ou Référence de boîte aux lettres ou Niveau hiérarchique
nomBL	Texte	Chaîne vide ou Nom de boîte aux lettres ou Jokers
tabNomsBL	Tableau chaîne	Tableau de noms de boîtes aux lettres (chemins d’accès)
tabAttribsBL	Tableau chaîne	Tableau d’attributs de boîtes aux lettres
tabHiérarBL	Tableau chaîne	Tableau de séparateurs hiérarchiques
abonnementsBL	Entier	0 = Lister toutes les boîtes aux lettres disponibles 1 = Lister uniquement les boîtes aux lettres abonnées
Résultat	Entier	Code d'erreur

Description

La commande IMAP_ListMBs retourne la liste des boîtes aux lettres disponibles pour l’utilisateur connecté, ainsi que les informations liées. Si la commande échoue, les tableaux sont retournés vides.

réfBL et nomBL doivent être traités conjointement, car la liste des boîtes aux lettres résultante dépendra de la combinaison des valeurs de ces deux paramètres.

Si vous passez 1 dans le dernier paramètre, abonnementsBL, la liste retournée est restreinte aux boîtes aux lettres auxquelles l’utilisateur est abonné (voir la commande IMAP_SubscribeMB).
Lorsque l’exécution de IMAP_ListMBs prend beaucoup de temps — à cause d’un grand nombre de boîtes aux lettres à examiner, d’une structure hiérarchique complexe, etc. — vous pouvez :

soit utiliser des jokers (voir ci-dessous),
soit passer 1 dans le paramètre abonnementsBL pour lister uniquement les boîtes aux lettres définies via la commande IMAP_SubscribeMB.

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

Le paramètre réfBL doit être combiné avec le paramètre nomBL afin de déterminer les boîtes aux lettres à utiliser. La référence de boîte aux lettres (réfBL) est l’équivalent d’un Répertoire de travail courant sur les systèmes Unix. En d’autres termes, le nom de la boîte aux lettres (nomBL) sera considéré comme un nom de fichier situé dans le répertoire désigné par la référence (réfBL). Attention, les spécifications IMAP indiquent que l’interprétation de la référence (réfBL) est “liée à l’implémentation” — ce qui signifie qu’elle n’est pas obligatoire. Il est donc fortement recommandé de prévoir un mode opératoire n’utilisant pas le paramètre réfBL afin de pouvoir dialoguer avec des serveurs plus anciens n’interprétant pas ce paramètre.

Si réfBL est une chaîne vide, seul le paramètre nomBL sera utilisé pour lister les boîtes aux lettres.
Si réfBL contient le nom d’une boîte aux lettres ou un niveau hiérarchique de boîtes aux lettres, il sera utilisé pour définir le contexte à partir duquel le paramètre nomBL sera interprété.

Note : Il est fortement recommandé de placer un séparateur hiérarchique à la fin du paramètre réfBL lorsqu’il est utilisé, afin d’assurer la compatibilité de la commande quel que soit le serveur IMAP utilisé.

La valeur à passer dans le paramètre nomBL dépend de celle du paramètre réfBL. Si nomBL est une chaîne vide, le séparateur hiérarchique est retourné.

Note : Si vous mettez en place un système de connexions multiples à l’aide du paramètre réfBL, vous devez permettre à l’utilisateur de placer ou non un séparateur hiérarchique au début du nom de la boîte aux lettres. En effet, la gestion du séparateur en début de nom varie d’un serveur à l’autre, voire entre deux gestionnaires de messagerie sur le même serveur. Dans certains cas, ce caractère signifiera “ne pas tenir compte du paramètre réfBL”, dans d’autres cas les deux paramètres seront concaténés et le caractère séparateur sera ignoré.

Le tableau tabNomsBL reçoit la liste des noms de boîtes aux lettres disponibles.
Le tableau tabAttribsBL reçoit la liste des attributs des boîtes aux lettres disponibles.

Attributs des boîtes aux lettres
Quatre attributs sont disponibles :

\Noinferiors : aucun niveau hiérarchique inférieur n’existe ni ne peut être créé.
\Noselect : ce nom ne peut être utilisé en tant que boîte aux lettres sélectionnable.
\Marked : le serveur a marqué la boîte aux lettres comme “intéressante” ; la boîte aux lettres contient probablement des messages nouveaux par rapport à sa dernière sélection.
\Unmarked : la boîte aux lettres ne contient pas de messages nouveaux par rapport à sa dernière sélection.

Le tableau tabHiérarBL reçoit la liste des séparateurs hiérarchiques des boîtes aux lettres disponibles.
Le séparateur hiérarchique est le caractère utilisé pour délimiter les niveaux hiérarchiques dans un nom de boîte aux lettres. Vous pouvez utiliser ce caractère pour créer des boîtes aux lettres “filles” ou pour remonter ou descendre les niveaux hiérarchiques. Tous les sous-éléments d’un niveau hiérarchique principal utilisent le même caractère séparateur.

Le paramètre abonnementsBL vous permet d’indiquer si vous souhaitez ne récupérer que la liste des boîtes aux lettres auxquelles l’utilisateur est abonné : pour cela, passez 1 dans abonnementsBL.
Si vous passez 0 ou omettez ce paramètre, toutes les boîtes aux lettres disponibles sont listées.

Exemple 1

L’exemple suivant :

IMAP_ListMBs(imap_ID;"4DIC/Work/";"Test";tabNomsBL;tabAttribsBL;tabHiérarBL)

... retourne toutes les boîtes aux lettres disponibles depuis la boîte “4DIC/Work/Test”.
Rappelons que si le serveur IMAP n’interprète pas les paramètres comme vous le souhaitez, n’utilisez pas le paramètre réfBL et concaténez les valeurs de réfBL et nomBL dans le paramètre nomBL :

IMAP_ListMBs(imap_ID;"";"4DIC/Work/Test";tabNomsBL;tabAttribsBL;tabHiérarBL)

Exemple 2

L’exemple suivant :

IMAP_ListMBs(imap_ID;"";"";tabNomsBL;tabAttribsBL;tabHiérarBL)

... retourne le séparateur hiérarchique.

Utiliser des jokers

Vous pouvez utiliser des jokers dans les paramètres réfBL et nomBL afin de faciliter la sélection de boîte aux lettres. Vous trouverez ci-dessous un exemple utilisant des jokers usuels, mais notez que l’interprétation des jokers dépend du serveur IMAP. Il est donc possible que ces exemples ne fonctionnent pas. Dans ce cas, vérifiez les jokers de votre serveur IMAP.

“ * ” remplace tout caractère à son emplacement :

IMAP_ListMBs(imap_ID;"";"*";tabNomsBL;tabAttribsBL;tabHiérarBL)

... retourne toutes les boîtes aux lettres disponibles pour l’utilisateur connecté.

IMAP_ListMBs(imap_ID;"";"Suivi*";tabNomsBL;tabAttribsBL;tabHiérarBL)

... retourne toutes les boîtes aux lettres disponibles débutant par la racine “Suivi”.

“ % ” est semblable à “ * ”, mais ne remplace pas le séparateur hiérarchique. Si le joker “ % ” est le dernier caractère du paramètre nomBL, les niveaux hiérarchiques correspondants sont également retournés. Si ces niveaux hiérarchiques ne sont pas des boîtes aux lettres sélectionnables, ils sont retournés avec l’attribut \Noselect (voir paragraphe “Attributs des boîtes aux lettres”) :

IMAP_ListMBs(imap_ID"";"Suivi/%";tabNomsBL;tabAttribsBL;tabHiérarBL)

... retourne toutes les boîtes aux lettres disponibles débutant par la racine “Suivi”, plus un sous-niveau hiérarchique supplémentaire.

Le joker “%” peut être utile lors d’une analyse niveau par niveau de la hiérarchie des boîtes aux lettres. Imaginons la hiérarchie de boîtes aux lettres suivante :

INBOX
   BoîteA
      BoîteAA
      BoîteAB
   BoîteB
      BoîteBA
      BoîteBB
   BoîteC
      BoîteCA
      BoîteCB

IMAP_ListMBs(imap_ID;"";"%";tabNomsBL;tabAttribsBL;tabHiérarBL)

... retourne INBOX, BoîteA, BoîteB et BoîteC.

IMAP_ListMBs(imap_ID;"";"BoîteA%";tabNomsBL;tabAttribsBL;tabHiérarBL)

... retourne BoîteAA et BoîteAB.

A l’aide de cette technique, vous pouvez proposer à l’utilisateur une certaine flexibilité sans le noyer sous les informations pouvant être retournées par un appel du type

IMAP_ListMBs(imap_ID;"";"*";tabNomsBL;tabAttribsBL;tabHiérarBL).

Notez que les serveurs IMAP eux-mêmes peuvent limiter le nombre de niveaux à analyser.