Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script

Chapitre 9 : Interface de messagerie de TSD (Tivoli Service Desk) Script

Retour à la table des matières


Introduction

La messagerie électronique est l'un des domaines d'application logicielle dont l'expansion est la plus rapide. Internet et les intranets d'entreprise reposent sur la messagerie électronique pour fournir un agent de communications viables.

La messagerie électronique permet d'établir différents types de communications :

Mécanisme de stockage et de retransmission

L'un des avantages présenté par un réseau de messagerie électronique est le mécanisme de stockage et de retransmission.

Ce mécanisme de stockage et de retransmission permet à un utilisateur d'envoyer un message à un deuxième utilisateur même si ce dernier n'est pas connecté au réseau de messagerie électronique.

Le serveur stocke le message envoyé par le premier utilisateur et le retransmet au deuxième utilisateur lorsque celui-ci consulte sa boîte aux lettres. Ce mécanisme permet d'établir une communication asynchrone entre deux utilisateurs. Ce type de communication signifie que les opérations de communication s'effectuent indépendamment du temps.

API de communication

La plupart des fournisseurs de messagerie électronique publient leurs propres API (interface de programmation d'application) dans des formats qui permettent à des applications d'autres fournisseurs de communiquer avec leur infrastructure de messagerie. Une API correspond à un ensemble de routines qu'une application utilise pour demander et exécuter les services de bas niveau d'un système d'exploitation.

L'utilisation d'API permet aux fournisseurs de logiciels de prendre en charge des opérations spécialisées. Cela signifie, toutefois, qu'une application utilisant ces API doit s'exécuter dans un système propriétaire afin de tirer avantage des fonctionnalités de la messagerie.

Remarque : Le protocole de messagerie Internet (SMTP/POP) n'est pas une API.

Le protocole VIM

A la différence des API de messagerie propres aux fournisseurs, le protocole VIM (messagerie indépendante du fournisseur) ne dépend pas des formats propres aux fournisseurs. En utilisant le protocole VIM, un développeur peut créer une application s'exécutant sur n'importe quelle plateforme et supprotant les fonctions de messagerie créées dans l'application.

Le protocole d'interface VIM a été conçu par le consortium VIM auquel participent les membres suivants :

MAPI

Le protocole MAPI (interface de programmation d'application de messagerie) correspond à un autre protocole de messagerie courant supporté par le langage TSD Script. Il s'agit d'un produit Microsoft. MAPI présente des fonctions similaires à VIM et permet les échanges électroniques de la même manière que VIM.

L'interface de messagerie TSD Script communique avec VIM et MAPI.

Remarque : Les instructions suivantes ne sont pas supportées pour le protocole MAPI :

SMTP

Le protocole SMTP (Simple Mail Transfer Protocol) fournit les mécanismes de transmission de courrier électronique :

POP3

POP3 (Post Office Protocol - version 3) permet à un poste de travail d'accéder dynamiquement à une case à courrier sur un serveur hôte. Généralement, cela signifie que le serveur POP3 permet à un poste de travail d'extraire le courrier électronique que le serveur conserve à son attention.

Remarque : Les instructions suivantes ne sont pas supportées pour les protocoles SMTP et POP3 :

Utilisation de la messagerie TSD Script avec les protocoles admis

L'interface de messagerie TSD Script fournit aux programmeurs des outils de développement d'applications compatible avec la messagerie. Actuellement, cette interface supporte trois protocoles :

L'interface de messagerie TSD Script présente une certaine souplesse dans l'élaboration d'applications :

Mise en oeuvre de l'interface de messagerie TSD Script

L'interface de messagerie TSD Script vous permet de créer des programmes TDS Script afin :

Terminologie de l'interface de messagerie TSD Script

Cette section présente quelques termes décrivant la mise en oeuvre de l'interface de messagerie TSD Script.

Carnets d'adresses

Un carnet d'adresses correspond à l'emplacement dans lequel les informations utilisateur, les adresses, les listes de messagerie, entre autres, sont stockées. Généralement, le carnet d'adresses est géré par l'administrateur de messagerie.

Il existe deux types de carnets d'adresses : public et privé.

L'interface de messagerie TSD Script supporte la fonction de lecture d'un carnet d'adresses publiques uniquement pour le protocole VIM.

Entité

Une entité correspond à une personne ou à un programme qui envoie ou reçoit des messages électroniques.

Fichiers joints

Les fichiers joints correspondent à des fichiers qui peuvent être joints à un message. Ils peuvent être de tous formats. Il en va de la responsabilité de l'expéditeur et du destinataire d'interpréter ces fichiers correctement.

Boîte de réception

Une boîte de réception est un fichier particulier supportant la lecture et le marquage de messages dans le protocole POP3. Il stocke les messages extraits du serveur POP3 et fournit un mécanisme permettant aux messages de porter la mention lu ou non-lu.

MsgCntnr sert d'indicateur de paramètre à la boîte de réception pour SMTP/POP3.

Administrateur de la messagerie

L'administrateur de la messagerie est la personne en charge du serveur de messagerie. Cette personne peut être responsable de la gestion des comptes utilisateur et du volume de messages stocké sur le réseau.

Boîte aux lettres

Une boîte aux lettres correspond à l'emplacement physique affecté à une entité individuelle. La boîte aux lettres stocke les messages au moment de leur distribution. Elle est également désignée par le terme de conteneur de messages.

Message

Un message correspond à tout objet pouvant transiter dans un système de messagerie et pouvant être stocké dans le conteneur de messages.

Client de messagerie

Un client de messagerie correspond à une interface permettant à un utilisateur final :

Conteneur de messages

Un conteneur de messages correspond à l'emplacement de stockage des messages reçus. Il est synonyme de boîte aux lettres.

En-tête de message

Un en-tête de message est un en-tête contenant des informations relatives :

Eléments de message

Un élément de message correspond à une liste d'éléments. Un élément de message peut être de deux types :

Type de message

Un type de message détermine le format et la sémantique du contenu du message.

Courrier

Les courriers correspondent aux messages à proprement parler. Plusieurs types sont supportés par le protocole VIM.

L'interface de messagerie TSD Script supporte uniquement les courriers de type texte.

Serveur

Le serveur correspond à la portion du système de messagerie qui gère :

Le serveur est également appelé "programme expéditeur"

Adresse utilisateur

L'adresse utilisateur correspond à l'emplacement de la boîte aux lettres du destinataire d'un message. Tous les systèmes de messagerie ont leur propre format d'adressage.

L'adressage de message est l'une des opérations les plus complexes dans le développement d'une application de messagerie. L'interface de messagerie TSD Script a été développée pour communiquer avec tous les systèmes de messagerie compatibles avec les protocoles VIM, MAPI et SMTP/POP. Il est toutefois important de prendre en compte les besoins du système de messagerie sous-jacent utilisé lors du développement d'applications de messagerie ou lors de leurs extensions.

ID utilisateur

Un ID utilisateur correspond à un identificateur unique affecté à une entité. Il permet à une entité de se connecter au serveur de messagerie.

Structures d'enregistrement de la messagerie TSD Script


Les sections ci-après sont extraites du fichier TSD Script mail.kb. Pour plus d'informations, reportez-vous à la section "Fichier Mail.kb" à la fin de ce chapitre.

Fichier en-tête

Les types suivants sont définis pour l'interface de messagerie TSD Script. En fonction de la définition du système de messagerie, certains types peuvent être facultatifs. EntityName et Address sont les seuls types supportés par le protocole de messagerie Internet. SMTP/POP requiert la mention de Address ; EntityName est facultatif.

MAILContainer is INTEGER;
MAILSession is INTEGER;
MAILRef is REAL;
MAILName is RECORD;
  EntityType        : INTEGER;
  NameType          : INTEGER;
  AddressBookName   : STRING;
  EntityName        : STRING;
  AddressType     : INTEGER; 
  Address         : STRING; 
  CharSet:            : STRING; 
              END; 

Description des types utilisés dans l'exemple précédent.

Définition des éléments de message

L'enregistrement suivant permet de définir un élément de message.

MAILItem is RECORD
  Class         : INTEGER;
  Type                      : STRING; 
  Name            : STRING; 
  BufferType    : INTEGER;
  BufferData    : STRING;
              END; 

Description des types utilisés dans l'exemple précédent.

En l'absence d'accord privé entre l'expéditeur et les destinataires d'un message, il est préférable que les éléments de la serie ISO-8859 soient utilisés à la place de tout autre jeu de caractères.

En-tête de message

Cet enregistrement comporte les informations d'en-tête d'un message à envoyer.

Dans MAPI, seul le type Subject est fonctionel, les autres types ne sont donc pas supportés.

Le protocole de messagerie Internet supporte uniquement les types Subject et InReplyTo.

Etat : 
MAILSendHeader is RECORD 
  Subject                       : STRING; 
  Priority                      : INTEGER; 
  DeliveryReport      : BOOLEAN;
  NonDeliveryReport   : BOOLEAN;
  NonDeliveryContents : BOOLEAN;
  Encrypt             : BOOLEAN;
  Sign                          : BOOLEAN; 
  ExpirationDate      : DATE
  ConversationID                       : LIST of STRING;
  Sensitivity                   : INTEGER; 
  InReplyTo                            : STRING;
  RespondBy                     : DATE; 
  KeyWord             : LIST of STRING;
  ReturnReceipt                        : BOOLEAN; 
  Save                : BOOLEAN;
  CharSet:            : STRING;
              END; 

Description des types utilisés dans l'exemple précédent.

Remarque : NORMAL correspond à la valeur par défaut.

En l'absence d'accord privé entre l'expéditeur et les destinataires d'un message, il est préférable que les éléments de la serie ISO-8859 soient utilisés à la place de tout autre jeu de caractères.

Attributs de message

Cet enregistrement définit les attributs d'en-tête de message lors de l'envoi d'un message.Les attributs d'en-tête à plusieurs valeurs sont déclarés en tant que listes.
Dans MAPI, les seuls types supportés sont :

Le protocole de messagerie Internet supporte les types suivants; :

L'exemple suivant présente des attributs d'en-tête de message.

MAILReadHeader is RECORD
  Type                      : STRING; 
  FromName                  : STRING; 
  FromAddress               : STRING; 
  Subject                       : STRING; 
  MessageDate               : DATE; 
  Priority                      : INTEGER; 
  Sign                          : BOOLEAN; 
  NestingDepth                         : INTEGER;
  UniqueMsgID                   : STRING; 
  Sensitivity                   : INTEGER; 
  InReplyTo                            : STRING;
  RespondBy                     : DATE; 
  ReturnReceipt                        : BOOLEAN;
  ConversationID                       : LIST of STRING; 
  KeyWords                             : LIST of STRING;
  AddressType     : INTEGER; 
  FromCharSet               : STRING;
  SubjectCharSet            : STRING;
              END; 

Les types figurant dans cet exemple sont décrits ci-après :

En l'absence d'accord privé entre l'expéditeur et les destinataires d'un message, il est préférable que les éléments de la serie ISO-8859 soient utilisés à la place de tout autre jeu de caractères.

Récapitulatif de message

Cet enregistrement extrait un récapitulatif des attributs de message lors de l'analyse des messages dans le conteneur de messages.

Dans MAPI, seul le type MsgReference est supporté.

Tous les types sont supportés dans le protocole de messagerie Internet à l'exception du type Priority.

L'exemple suivant présente les attributs de message récapitulatif.

MAILMsgSummary is RECORD
  MsgReference              : MAILRef;
  Type                      : STRING;
  UnreadMail                : BOOLEAN;
  FromName                  : STRING;
  FromAddress               : STRING;
  Priority                      : INTEGER; 
  Subject                       : STRING; 
  MessageDate               : DATE;
  FromCharSet               : STRING;
  SubjectCharSet            : STRING;
              END; 

Description des types utilisés dans l'exemple précédent.

En l'absence d'accord privé entre l'expéditeur et les destinataires d'un message, il est préférable que les éléments de la serie ISO-8859 soient utilisés à la place de tout autre jeu de caractères.

Enregistrement de filtrage

Cet enregistrement permet de filtrer le type des messages extraits lors du processus d'analyse des messages.

Les protocoles MAPI et SMTP/POP ne supportent pas le filtrage.

L'exemple suivant présente des attributs de filtrage.

MAILFilter is RECORD
  MessageType                   : STRING;
  UniqueMsgID                   : STRING;
  Sent                          : BOOLEAN;
  Keyword                       : STRING;
  From                          : STRING;
  Subject                       : STRING;
  Date                          : DATE;
  Priority                      : INTEGER;
  Sign                          : BOOLEAN;
  ConversationID                : STRING;
  Sensitivity                   : INTEGER;
  RespondBy                     : DATE;
              END; 

Description des types utilisés dans l'exemple précédent.

D'autres valeurs définies par l'utilisateur sont également acceptées.

MAILInfoRec

La structure d'enregistrement MAILInfoRec est utilisée dans la fonction MAILQueryDefaults afin d'extraire les valeurs par défaut du système de messagerie.
L'exemple suivant présente l'organisation de la structure MailInfoRec :

MAILInfoRec is RECORD
  Product:                        STRING;
  SpecVersion:                    INTEGER;
  MaxSubjectLen:                  INTEGER;
  MaxTextLen:                     INTEGER;
  PathNameReq:                    BOOLEAN;
  UserNameReq:                    BOOLEAN;
  PasswdReq:                      BOOLEAN;
  DefPathName:                    STRING;
  DefUserName:                    STRING;
  DefCharSet:                     STRING;
              END;

Description des types utilisés dans l'exemple précédent.

Carnets d'adresses

TSD Script vous permet de répertorier les noms des destinataires de messages dans un carnet d'adresses (les carnets d'adresses ne sont pas supportés par le protocole MAPI ou SMTP/POP). TSD Script ne supporte pas les carnets d'adresses imbriqués.

L'enregistrement suivant permet d'extraire les entrées du carnet d'adresses.

MAILABEntry is RECORD 
  Name            : STRING;
  AddressType     : INTEGER;
  Address         : STRING;
  Comments        : STRING;
  EntryType       : INTEGER;
              END; 

Remarque : Les utilisateurs finaux ne peuvent pas apporter de modification à un carnet d'adresses.

Description des types utilisés dans l'exemple précédent.

Mise en oeuvre de l'interface de messagerie TSD Script

Cette section vous guide dans l'implémentation d'un exemple de petit programme TSD Script (envoi de mail.kb). Ce programme permet d'envoyer un courrier de l'utilisateur dont l'ID est "BILL" à un utilisateur dont l'ID est "JOHN".

Ajout de l'interface de messagerie TSD Script à un programme TSD Script

Les programmes TSD Script peuvent utiliser l'interface de messagerie TSD Script en ajoutant le module de messagerie TSD Script à la section USES d'une base de connaissances.
Le module de messagerie TSD Script figure dans le fichier mail.kb. Il a été installé automatiquement dans le répertoire d'installation de la boîte à outils du développeur (Developer's Toolkit). Le fichier mail.kb comporte la définition des structures d'enregistrements, des constantes et des codes retour utilisés par les fonctions de la messagerie TSD Script.

Le fragment de code ci-après présente la première étape d'ajout de l'interface de messagerie TSD Script à un programme :

Knowledgebase SENDMAIL;
USES
    mail;
PUBLIC
PROCEDURE SendMailMessage;
PRIVATE 
    ROUTINES 
PROCEDURE SendMailMessage IS
ACTIONS 
    (*corps de la procédure *)
              END; 

Initialisation de l'interface de messagerie TSD Script

Avant d'appeler les fonctions de la messagerie TSD Script Mail, une application doit tout d'abord appeler l'instruction MAILInitialize. Cette fonction initialise les ressources et l'organisation des données utilisées par l'interface de messagerie TSD Script.

L'instruction MAILInitialize doit indiquer dans ses paramètres le protocole qu'elle compte utiliser :

A la suite de l'initialisation de l'interface de messagerie TSD Script, vous pouvez ouvrir autant de sessions de messagerie que vous le désirez.

MAILInitialize(OMI_VIM_INTERFACE)

Remarque : Une fois que l'appel de l'instruction MailInitialize a abouti, l'instruction MailTerminate doit toujours être appelée avant la sortie du programme.

Ouverture d'une session

Après avoir initialisé l'interface de messagerie TSD Script, vous pouvez ouvrir une session à l'aide de l'instruction MAILOpenSession. Vous devez indiquer dans cette instruction MAILOpenSession :

L'exemple de code suivant :

Remarque : Utilisez OMISEL_CP850 pour OS/2 et OMISEL_CP1252 pour Windows.

Vous pouvez également transmettre $Unknown, auquel cas le système utilise le jeu de caractères par défaut.

Remarque : Utilisateurs de Microsoft Windows 95/98 : veuillez consulter la section relative aux remarques concernant l'instruction MailOpenSession dans TSD Script Language Reference.

Pour tout état d'échec, utilisez l'instruction MailGetLastErrorType.

PROCEDURE SendMailMessage
VARIABLES 
    sessID:       MailSession; 
    rc:Integer;
ACTIONS 
    rc := MAILInitialize(OMI_VIM_INTERFACE);
     IF (rc <> KML_SUCCESS) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit.
                       Error code is ' & rc <);
        Exit;
              END; 
     rc := MAILOpenSession('M:\APPS\CCMAIL\CCDATA',
                          'BILL','K2K2', OMISEL_CP850,
                           sessID,OMI_VIM_INTERFACE);
     IF (rc <> KML_SUCCESS) THEN
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        MailTerminate(OMI_VIM_INTERFACE);
        Exit; 
              END; 
        (* Envoi du message *)
     rc := MAILCloseSession(sessID);
     IF (rc <> KML_SUCCESS) THEN
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        MailTerminate(OMI_VIM_INTERFACE); 
        Exit; 
              END; 
     rc := MAILTerminate(OMI_VIM_INTERFACE);
              END; 

Une session valide est maintenant ouverte. Avant tout envoi de message, les tâches suivantes doivent être effectuées :

  1. Initialisation de l'enregistrement de l'en-tête du message.
  2. Initialisation de la liste des destinataires.
  3. Définition de la liste des destinataires.
  4. Définition de la liste des éléments de message.

Initialisation de l'en-tête du message

Dans l'exemple ci-après, seules les zones Subject et Priority de la structure d'enregistrement MAILSendHeader sont définies. Toutes les autres zones présentent la valeur $Unknown.

msgHeader:MAILSendHeader;
msgHeader.Subject := 'Floor Plan';
msgHeader.Priority := OMI_HIGH_PRIORITY; 

Initialisation de la liste des destinataires

Si, par exemple, vous désirez envoyer un message à un destinataire nommé John, La liste des destinataires ne comporte qu'un seul élément qui est l'adresse "JOHN".

L'exemple suivant présente la liste toList qui correspond à une liste des enregistrements MAILName.

    toList:       LIST of MAILName; 
toRecipient:MAILName;

Définition d'un destinataire

Il existe deux manières de désigner un destinataire : son adresse ou son nom.

L'enregistrement MailName comporte un type nommé EntityType qui désigne le type de destinataire. Si le destinataire correspond à un utilisateur ou à un programme unique, le type EntityType doit présenter la valeur OMISEL_ENTITY. Si le destinataire du message correspond à un groupe (liste de diffusion), le type EntityType doit présenter la valeur OMISEL_GROUP.

Définition d'un destinataire à l'aide de son nom

Si vous définissez un destinataire à l'aide de son nom, vous devez initialiser les types suivants dans l'enregistrement MAILName :

L'entrée du type NameType est basé sur le nom de l'application de messagerie. Par exemple :

Définition d'un destinataire à l'aide de son adresse

Si vous définissez un destinataire à l'aide de son adresse, vous devez initialiser les zones AddressType et Address de l'enregistrement MAILName :

La zone AddressType désigne le type de l'adresse. Par exemple : OMISEL_CCMAIL, OMISEL_NOTES, OMISEL_MHS, etc. Vous trouverez une liste complète des valeurs AddressType dans les descriptions de types situées plus loin dans ce chapitre.

Le type Address comporte la chaîne d'adresse dans le format indiqué par le type AddressType. Pour connaître le format d'adresse correct, reportez-vous à la documentation délivrée par votre fournisseur d'outil VIM.

Pour SMTP/POP, les destinataires doivent être indiqués au moyen de leur adresse. La zone nom est facultative.

Remarque :
Lorsque MAILReadMessage lit des messages, l'instruction renseigne les types de spécifications Name et Address de l'enregistrement MAILName tout en extrayant les messages.

L'instruction msgCntnr désigne la boîte de réception lorsqu'elle est utilisée pour le support de SMTP/POP3 Indiquez le destinataire à l'aide de son nom et utilisez le carnet d'adresses par défaut (conformément au fragment de code ci-après) :

toRecipient.EntityType := OMISEL_ENTITY;
toRecipient.AddressBookName := '';
toRecipient.EntityName := 'JOHN';
ListInsert(toList, toRecipient, $After); 

Remarque : Les instructions toList et ccList peuvent être déclarées de la même manière.

Définition de la liste des éléments de message

L'étape suivante concerne la création de la liste des éléments de message. Les éléments suivants doivent être indiqués :

Cet exemple de programme comporte la liste d'éléments de message :

(* Création de la liste des éléments de message *)
(* Premier élément correspondant au courrier *) 
Item.Class      := OMISEL_NOTE_PART; 
    Item.Type       := OMI_TEXT;
    Item.Name       := 'Title for the
                       note part';
    Item.BufferType := OMI_ACTUAL_DATA;
    Item.BufferData := 'Hi John. I have' &
                       'enclosed the floor' &
                       'plan layout in the' &
                       'file attachment. ';
    Name.Address    := 'JOHN/ACME CORPORATION'
    ListInsert(Items, Item, $After);
   (* Second élément correspondant à un fichier joint *)
Item.Class      := OMISEL_ATTACH;
    Item.Name       := 'image.pcx';
    Item.BufferType := OMI_FILE_DATA;
    Item.BufferData := 'D:\TMP\PAPANIM.PCX';
    ListInsert(Items, Item, $After);

Remarque : Un exemple SMTP/POP pour Name.Address se présente sous la forme suivante :

Name.Address := 'john@acme.com'

Ecriture de la procédure SendMailMessage

La procédure SendMailMessage peut être écrite de la manière suivante :

PROCEDURE SendMailMessage IS
VARIABLES 
    header:       MAILSendHeader;
    Items:        LIST of MAILItem;
    Item:         MAILItem;
    name:         MAILName;
    toList:       LIST of MAILName;
  rc              :INTEGER; 
    sessID:       MailSession;
ACTIONS 
    rc := MAILInitialize(OMI_VIM_INTERFACE);
    IF (rc < 1) THEN
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit.
                       Error code is ' & rc <);
        Exit;
              END; 
    rc := MAILOpenSession('M:\APPS\CCMAIL\CCDATA',
                          'BILL','K2K2',
                     OMISEL_CP850, sessID,
OMI_VIM_INTERFACE);
    IF (rc < 1) THEN
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit.
                       Error code is ' & rc <);
        MailTerminate(OMI_VIM_INTERFACE);
        Exit;
                  END; 
    (* Envoi du message *)
    (* Définition de l'enregistrement de l'en-tête *)
    header.subject := 'Floor Plan';
    header.Priority := OMI_HIGH_PRIORITY;
    (* Création de la liste des éléments de message *)
(* Premier élément correspondant au courrier *)
    Item.Class      := OMISEL_NOTE_PART;
    Item.Type       := OMI_TEXT;
    Item.Name       := 'Title for
                      the note part';
    Item.BufferType := OMI_ACTUAL_DATA;
    Item.BufferData := 'Hi John. I have enclosed'&
                       'the floor plan layout in'&
                       'the file attachment. ';
    ListInsert(Items, Item, $After);
    (* Second élément correspondant à un fichier joint *)
    Item.Class      := OMISEL_ATTACH;
    Item.Name       := 'image.pcx';
    Item.BufferType := OMI_FILE_DATA;
    Item.BufferData := 'D:\TMP\PAPANIM.PCX';
    ListInsert(Items, Item, $After);
    (* Définition du destinataire *)
    name.EntityType := OMISEL_ENTITY;
    name.AddressBookName := '';
    name.EntityName := 'JOHN'
    ListInsert(toList, name, $After);
    rc := MailSendMessage(SESSID, OMI_MAIL, header,
                          toList, $UNKNOWN,$UNKNOWN,
                           Items);
    IF (rc < 1) THEN
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit.
                       Error code is ' & rc <);
        ELSE ('Mail sent successfully');
              END; 
    rc := MAILCloseSession(sessID);
    IF (rc < 1) THEN
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit.
                       Error code is ' & r <);
        MailTerminate(OMI_VIM_INTERFACE);
        Exit;
              END; 
    rc := MAILTerminate(OMI_VIM_INTERFACE);
              END; 

Lecture des messages dans le conteneur de messages

L'interface de messagerie TSD Script peut lire des messages figurant dans le conteneur de messages. Cette lecture s'effectue en deux étapes :

Remarque : Les filtres ne sont pas supportés pour SMTP/POP3.

L'exemple suivant présente un programme recevant du courrier :

KNOWLEDGEBASE mailrecv;
 
USES mail; 

    ROUTINES 

PROCEDURE ReadMail;

PRIVATE
    ROUTINES 

PROCEDURE ReadMail IS
VARIABLES
  sess :MAILSession;
  msgContainer :MAILContainer;
  toList :LIST OF MAILName;

  outfile         :FILE;
  numMessages     :INTEGER;
  msgSummary      :LIST OF MAILMsgSummary;
  summRec         :MAILMsgSummary;
  msgRef          :MAILRef;
  msgHeader       :MAILReadHeader;
  msgItems        :LIST of MAILItem;
  ccList, bccList :LIST of MAILName;
  nestedMsg       :BOOLEAN;
  reply           :string;
  rc              :INTEGER;
ACTIONS
   rc:=MAILInitialize(OMI_SMTP_POP_INTERFACE);
              IF rc < 1 THEN
    EXIT;
              END;
   rc:=MAILOpenSession('mozart.softart.com',
                      'Mr Totstuser@domain name',
                       'pass',$UNKNOWN,
                       sess,OMI_SMTP_POP_INTERFACE);
              IF rc < 1 THEN
             WinMessageBox($Desktop,'Error',$MBIconError,
                'Open session failed: '&rc);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
              END;
 rc:=MAILOpenMessageContainer (sess,
                              'c:\mail\inbox.idx',
                               msgContainer);
              IF rc < 1 THEN
             WinMessageBox($Desktop,'Error',$MBIconError,
                 'Open container failed: '&rc);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
              END;
 rc:= MAILScanMessages(msgContainer, OMI_UNREADONLY,
                      $Unknown, TRUE, numMessages,
                       msgSummary);
              IF rc < 1 THEN
     WinMessageBox($Desktop,'Error',$MBOK,
                   'Scan failed: '&rc);
 MAILCloseMessageContainer(msgContainer);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
              END;
 REPEAT
    IF numMessages > 0 THEN
         rc:=FOpen(outfile, 'mailtest.log', $CREATE);
              IF rc < 1 THEN 
             WinMessageBox($Desktop,'Error',$MBIconError,
                          'File Open failed: '&rc);
                EXITLoop;
ELSE
             FWriteLn(outfile, 'Number Read: ' &
                      numMessages);
            FOR msgSummary DO
                 summRec := msgSummary[$Current];
                 FWriteLn(outfile, 'Message Type: ' &
                          summRec.Type);
                 FWriteLn(outfile, 'Unread Mail: ' &
                          summRec.UnreadMail);
                 FWriteLn(outfile, 'FromName: ' &
                          summRec.FromName);
                 FWriteLn(outfile, 'FromAddress ' &
                          summRec.FromAddress);
                 FWriteLn(outfile, 'Priority: ' &
                          summRec.Priority);
                 FWriteLn(outfile, 'Subject: ' &
                          summRec.Subject);
                 msgRef := summRec.MSGReference;
                rc := MAILReadMessage(msgContainer,msgRef,
                                      0,msgHeader,
                                     msgItems,toList,
                                     ccList,bccList,
                                      nestedMsg);
              IF rc < 1 THEN
                WinMessageBox($Desktop,'Error',
                              $MBIconError,
                              'ReadMessage failed: '&rc);
          FClose(outfile); 
                EXITLoop;
               ELSE
                    MAILReleaseMessageReference
                        (msgContainer, msgSummary
                         [$Current].msgReference);
              FOR tolist DO
                 FWriteLn(outfile,'To Name: ' &
                          toList[$current].EntityName);
                 FWriteLn(outfile,'To Address: ' &
                          toList[$current].address);
              END;
              FWriteLn(outfile, ' ***Message Items**** ');
                 FOR msgItems DO
            FWriteLn(outfile,msgItems
                     [$current].Type);
            FWriteLn(outfile,msgItems
                     [$current].Name);
            FWriteLn(outfile,msgItems
                     [$current].BufferData);
              END;
            FWriteLn(outfile,
                    '*********************************
                     ******************* ');
            END; (*Fin de Else*)
          END; (*Fin de For LOOP*)
          FClose(outfile); 
       END;(*Fin de Else*)
    END;(*Fin de IF*)
 UNTIL TRUE;
 MAILCloseMessageContainer(msgContainer);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
 WinMessageBox($Desktop,'Program Complete',$MBOK,
              'Execution is complete.
               Check for output.');
              END;

Fermeture d'une session de messagerie TSD Script

Plusieurs sessions de messagerie TSD Script peuvent être ouvertes simultanément.

Pour fermer une session de messagerie TSD Script, appelez l'instruction MAILCloseSession. Les ressources système liées à cette session de la messagerie TSD Script sont libérées.

Sortie de l'interface de messagerie TSD Script

Si vous êtes prêt à sortir de l'interface de messagerie TSD Script, vous devez préalablement fermer toutes les sessions ouvertes, puis appeler l'instruction MAILTerminate.

Codes retour de la messagerie TSD Script

Cette section répertorie tous les codes d'erreur qui peuvent apparaître à l'exécution des instructions de l'interface de messagerie TSD Script. Des erreurs peuvent se produire à différents niveaux du traitement du message, aussi bien au niveau VIM ou MAPI qu'au niveau TSD Script. Les tableaux suivants décrivent les codes d'erreur qui peuvent apparaître à chacun de ces niveaux.

Remarque : Tous les appels de l'interface de messagerie TSD Script renvoient la valeur 1 si la fonction exécutée aboutit. Dans le cas contraire, un numéro négatif est renvoyé.

Codes d'erreur générés au niveau VIM

La liste ci-après répertorie tous les codes d'erreur qui peuvent être générés au niveau VIM.

Erreur Valeur Commentaire
OMISTS_FAILURE -1 Incident d'ordre général.
OMISTS_FATAL -2 Une erreur fatale s'est produite. La poursuite de l'utilisation
du système est impossible tant que l'incident n'est pas résolu.
OMISTS_ALL_PARAMS_REQUIRED -3 MAILOpenSession renvoie ce message lorsqu'un
chemin d'accès, un nom ainsi qu'un mot de passe sont requis par le système de messagerie sous-jacent.
OMISTS_ATTACHMENT_NOT_FOUND -4 Le fichier joint indiqué (dans un MAILSendMessage)
est introuvable.
OMISTS_BAD_PARAM -5 Un paramètre requis est inconnu, non compris dans la
plage autorisée ou non valide.
OMISTS_BUF_TOO_SMALL -6 L'interface de messagerie TSD Script utilise des mémoires tampon pour extraire
des valeurs du système de messagerie. Ce code retour
indique que la mémoire tampon utilisée est insuffisante pour pouvoir contenir la valeur renvoyée.
OMISTS_CONV_NOT_SUPPORTED -7 La conversion indiquée n'est pas supportée pour cette implémentation.
OMISTS_INSUFFICIENT_MEMORY -8 Une opération interne a échoué à cause d'un espace mémoire disponible
insuffisant.
OMISTS_INVALID_CONFIGURATION -9 Une configuration sous-jacente non valide a été détectée.
OMISTS_INVALID_OBJECT
-10 Le descripteur d'objet (MAILSession, MAILContainer, MAILRef) est inconnu ou non valide. Par
exemple, le descripteur d'un message autre que du courrier ne peut pas
être transmis à des fonctions qui attendent un courrier.
OMISTS_INVALID_PASSWORD -11 Un mot de passe incorrect a été transmis à MAILOpenSession.
OMISTS_INVALID_SELECTOR -12 Un outil de sélection (OMISEL_*) inconnu dans ce contexte
a été transmis à l'instruction.
OMISTS_INVALID_SIGNATURE -13 Une signature incorrecte a été transmise à MAILVerifySignature,
ou le message a été endommagé.
OMISTS_NAME_EXISTS -14 Ce code retour n'est pas utilisé dans VIM.
OMISTS_NAME_NOT_FOUND -15 MAILSendMessage a validé le nom du destinataire immédiatement et ce nom a été localisé dans le carnet d'adresses indiqué. (Si aucun carnet d'adresses n'est indiqué, le
carnet d'adresses par défaut est utilisé).
OMISTS_NOT_SUPPORTED -16 La fonction appelée n'est pas supportée par cette implémentation.
OMISTS_NO_COMMON_CERTIFICATES -17 La signature MAILVerifyMessage signale qu'aucun certificat commun n'existe entre le destinataire et l'auteur.
OMISTS_NO_DEFAULT -18 MAILGetEntityName n'arrive pas à choisir parmi plusieurs sessions actives. Certaines implémentations peuvent renvoyer le
nom de la session qui est restée active le plus longtemps
plutôt que de renvoyer un code erreur
OMISTS_NO_MATCH -19 Aucune correspondance n'a été trouvée.
OMISTS_NO_SIGNATURE -20 La signature MAILVerifyMessage signale que le
message indiqué ne présente pas de signature.
OMISTS_NO_SUCH_ATTRIBUTE -21 L'attribut appelé n'est pas utilisé.
OMISTS_OPEN_FAILURE -22 Un incident dépendant de la plateforme utilisée s'est produit lors de l'ouverture ou de la création d'un fichier.
OMISTS_PASS_REQUIRED -23 MAILOpenSession indique qu'un mot de passe est requis
pour ouvrir une session dans cette implémentation.
OMISTS_READ_FAILURE -24 Un incident dépendant de la plateforme utilisée s'est produit lors de l'ouverture ou de la création d'un fichier.
OMISTS_UNSUP_TYPE -25 Un type de message autre que VIM_MAIL qui n'est pas supporté par cette implémentation a été transmis
au Message MAILSendMessage ou MAILSendDerived. Ou MAILReadMessage ne supporte pas la lecture
de ce type d'élément.
OMISTS_UNSUP_VERSION -26 Incompatibilité entre l'interface de messagerie TSD Script et
l'interface VIM sous-jacente.
OMISTS_WRITE_FAILURE -27 Un incident dépendant de la plateforme utilisée s'est produit lors de l'écriture d'un fichier.

Codes erreur générés au niveau MAPI

La liste ci-après répertorie tous les codes d'erreur qui peuvent être générés au niveau MAPI.

Erreur Valeur Commentaire
MAPI_USER_ABORT -201 L'utilisateur a annulé le processus. Cette fonction n'a pas abouti.
MAPI_E_FAILURE

-202 Un ou plusieurs incidents indéterminés se sont produits. La fonction
n'a pas abouti.
MAPI_E_LOGIN_ FAILURE

-203 L'utilisateur n'a pas réussi à se connecter. Aucun identificateur
de session n'a été renvoyé.
MAPI_E_DISK_FULL
-204 Le disque est plein.
MAPI_E_INSUFFICIENT
_MEMORY

-205 L'espace mémoire est insuffisant pour pouvoir poursuivre. La fonction
n'a pas abouti.
MAPI_E_TOO_MANY_SESSIONS

-208 Trop de sessions sont ouvertes simultanément.
MAPI_E_ TOO_MANY_FILES -209 Le nombre de fichiers joints est trop élevé.
MAPI_E_ TOO_MANY_RECIPIENTS -210 Trop de destinataires de message ont été indiqués.
MAPI_E_ATTACHMENT_NOT
_FOUND
-211 Un ou plusieurs fichiers qui doivent être joints au message
sont introuvables.
MAPI_E_ ATTACHMENT_OPEN_FAILURE -212 Un ou plusieurs fichiers qui doivent être joints au message
ne peuvent pas être ouverts.
MAPI_E_ ATTACHMENT_WRITE_FAILURE -213 Un fichier joint n'a pas pu être enregistré dans un fichier temporaire.
Vérifiez les droits du répertoire.
MAPI_E_UNKNOWN_RECIPIENT -214 Le destinataire est introuvable dans la liste des adresses.
MAPI_E_BAD_RECIPTYPE -215 Le type de destinataire n'est pas indiqué ou il n'est pas valide.
MAPI_E_INVALID_MESSAGE -217 Le numéro de référence du message n'est pas valide.
MAPI_E_TEXT_TOO_LARGE -218 Le texte du message est trop long.
MAPI_E_INVALID_SESSION -219 L'identificateur de la session n'est pas valide.
MAPI_E_TYPE_NOT
_SUPPORTED
-220 Un ou plusieurs types ne sont pas supportés par cette implémentation.
MAPI_E_AMBIGUOUS
_RECIPIENT
-221 Un ou plusieurs destinataires sont ambigus.
MAPI_E_INVALID_RECIPS -225 Un ou plusieurs destinataires ne sont pas valides.
MAPI_E_NOT_SUPPORTED -226 Cette fonction n'est pas supportée par l'implémentation sous-jacente.


Codes erreur générés par SMTP

Le tableau ci-après répertorie les codes erreur qui peuvent être générés par SMTP.

Erreur Valeur Commentaire
OMI_ERR_SMTP_OPENSESSION
_FAILURE
-3000 L'initialisation de toutes les données dans MAILOpenSession(..) a échoué.
OMI_ERR_SMTP_MAIL
_FAILURE
-3001 L'envoi de la commande mail au serveur SMTP a échoué.
OMI_ERR_SMTP_CLOSE
_FAILURE
-3002 L'envoi de la commande close au serveur SMTP a échoué.
OMI_ERR_SMTP_VERIFY
_FAILURE
-3003 Le serveur SMTP ne peut pas vérifier un utilisateur de la liste des destinataires.
OMI_ERR_ATTACH_FILE
_ERROR
-3004 Le fichier indiqué en tant que fichier joint n'existe pas ou
le format du nom du fichier est incorrect.
OMI_ERR_SMTP_OPEN_SERVER
_FAILURE
-3005 La connexion au serveur SMTP a échoué.
OMI_ERR_POP_OPEN_FAILURE -3006 La connexion au serveur POP a échoué.
OMI_ERR_INVALID_PASSWORD -3007 La vérification du mot de passe a échoué.
OMI_ERR_POP_STAT_FAILURE -3008 L'envoi de la commande stat au serveur POP a échoué.
OMI_ERR_POP_RETR_FAILURE -3009 L'envoi de la commande retr au serveur POP a échoué.
OMI_ERR_POP_DELE_FAILURE -3010 L'envoi de la commande delete au serveur POP a échoué.
OMI_ERR_POP_QUIT_FAILURE -3011 L'envoi de la commande quit au serveur POP a échoué.
OMI_ERR_SOCKET_FAILURE -3012 L'appel de la socket a échoué.
OMI_ERR_PARSE_MESSAGE
_FAILURE
-3013 L'appel de l'analyse de message a échoué.
OMI_ERR_INVALID_FILE -3014 La taille du fichier est égale à 0.
OMI_ERR_SERVICE_NOT
_AVAILABLE
-3421 Il peut s'agir d'une réponse d'une commande SMTP si le service sait qu'il doit être arrêté.
OMI_ERR_MAILBOX_BUSY -3450 La boîte aux lettres est probablement pleine.
OMI_ERR_LOCAL_ERROR_IN
_PROCESSING
-3451 L'action requise a été abandonnée à cause d'une erreur locale de traitement.
OMI_ERR_INSUFFCIENT
_SYSTEM_STORAGE
-3452 L'action requise a été abandonnée à cause d'un système de stockage insuffisant.
OMI_ERR_SYNTAX_ERROR -3500 Erreur de syntaxe, la commande n'a pas été identifiée.
OMI_ERR_SYNTAX_ERROR_IN
_PARAMETER
-3501 Erreur de syntaxe dans des paramètres ou des arguments.
OMI_ERR_COMMAND_NOT
_IMPLEMENTED
-3502 La commande n'a pas été mise en oeuvre.
OMI_ERR_SEQUENCE_ERROR -3503 Séquence de commande incorrecte.
OMI_ERR_PARAMETER_NOT
_IMPLEMENTED
-3504 Paramètre de commande non implémenté.
OMI_ERR_MAILBOX
_UNAVAILABLE
-3550 L'action requise n'a pas été effectuée : la boîte aux lettres n'est pas disponible.
OMI_ERR_USER_NOT_LOCAL -3551 Utilisateur en local ; essayez <chemin-réacheminement>
OMI_ERR_EXCEEDED
_STORAGE_ALLOCATION
-3552 L'action de messagerie requise a été abandonnée : espace mémoire insuffisant.
OMI_ERR_MAILBOX_NAME
_NOT_ALLOWED
-3553 Le nom de la boîte aux lettres n'est pas admis
OMI_ERR_TRANSACTION
_FAILED
-3554 La transaction a échoué
OMI_ERR_SOCKET_ERROR -3099 Erreur de communication de socket

Codes erreur générés par TSD Script

La liste ci-après répertorie tous les codes d'erreur qui peuvent être générés par TSD Script.

Erreur Valeur Commentaire
OMI_ERR_INVALID_BUFFER
_TYPE
-2000 Un type de mémoire tampon non valide a été indiqué dans l'enregistrement
Mail Item.
OMI_ERR_INVALID_BUFFER
_DATA
-2001 Données de mémoire tampon non valides.
OMI_ERR_NO_MEMORY -2002 Ressources de mémoire système épuisées.
OMI_ERR_INVALID_FILENAME -2003 Nom de fichier non valide.
OMI_ERR_NO_TOLIST -2004 Aucune liste "To" n'a été indiquée.
OMI_ERR_BAD_PARAM -2005 Un paramètre incorrect a été indiqué.
OMI_ERR_NO_NESTED
_MESSAGE
-2006 Aucun message imbriqué n'a été trouvé au niveau requis.
OMI_ERR_TOO_MANY_FILE
_NAMES
-2007 Le nombre de noms de fichiers indiqués est trop élevé.
OMI_ERR_UNSUPPORTED
_PROTOCOL
-2008 La valeur de l'argument de protocole n'est pas valide ou le
protocole n'est pas supporté.
OMI_ERR_UNSUPPORTED
_FEATURE
-2009 Cette fonction n'est pas disponible dans cette implémentation.
OMI_ERR_NOT_IMPLEMENTED -2010 Cette fonction n'a pas été implémentée.
OMI_ERR_UNKNOWN_ITEM
_CLASS
-2011 La classe de l'élément est inconnue.
OMI_ERR_INVALID_NOTE_PART -2012 La partie texte du message n'est pas valide.
OMI_ERR_MAPI_FAILURE -2013 Une erreur s'est produite dans la programmation de l'interface MAPI.
OMI_ERR_NOT_INITIALISED -2014 L'interface de messagerie n'a pas été initialisée. MailInitialize doit être appelé avant que l'interface de messagerie TSD Script ne soit utilisée.
OMI_ERR_COULD_NOT_LOAD
_DLL
-2015 La messagerie TSD Script n'a pas réussi à charger la bibliothèque MAPI ou VIM.
KML_ERR_UNKNOWN_ITEM
_CLASS
-5000 Une classe d'éléments inconnue a été indiquée.
KML_ERR_UNKNOWN_ITEM
_TYPE
-5001 Un type d'élément inconnu a été indiqué.
KML_ERR_UNKNOWN_BUFFER_TYPE -5002 Un type de mémoire tampon inconnu a été indiqué.
KML_ERR_UNKNOWN_BUFFER_DATA -5003 Des données de mémoire tampon inconnues ont été indiquées.

Constantes de la messagerie TSD Script

Le tableau ci-après présente les constantes valides de la messagerie TSD Script.

Constante Valeur
OMISEL_ADDRESS 1
OMISEL_ATTACH 6
OMISEL_BCC 9
OMISEL_CC 10
OMISEL_CCMAIL 11
OMISEL_CLASS 13
OMISEL_CP1252 16
OMISEL_CP437 17
OMISEL_CP850 18
OMISEL_ENTITY 26
OMISEL_FORWARD 33
OMISEL_GROUP 38
OMISEL_LMBCS 44
OMISEL_MHS 49
OMISEL_NOT_SUPPORTED 61
OMISEL_NOTE_PART 62
OMISEL_NOTES 63
OMISEL_REPLY 77
OMISEL_TO 97
OMISEL_UNICODE 99
OMISEL_UNKNOWN_RECIP_TYPE 101
OMISEL_UNWRAPPED_TEXT 105
OMISEL_X400 107
OMISEL_X500 108
OMI_MAIL 'VIM_MAIL'
OMI_RTF 'VIM_RTF'
OMI_DLR 'VIM_DLR'
OMI_NDLR 'VIM_NDLR'
OMI_PRIVATE 'VIM_PRIVATE'
OMI_PUBLIC 'VIM_PUBLIC'
OMI_RTRC 'VIM_RTRC'
OMI_TEXT 'VIM_TEXT'
OMI_UNWRAPPED_TEXT 'VIM_UNWRAPPED
_TEXT'
OMI_LOW_PRIORITY 0
OMI_NORMAL_PRIORITY 1
OMI_HIGH_PRIORITY 2
OMI_HISTORY 1
OMI_INHERIT_CONTENTS 2
OMI_ALL_RECIPIENTS 4
OMI_UNREADONLY 2
OMI_NORMAL_SENS 0
OMI_PRIVATE_SENS 1
OMI_PERSONAL_SENS 2
OMI_CO_CONFID_SENS 3
OMI_APP_DEF_SENS 16384
OMI_FILE_DATA 1
OMI_ACTUAL_DATA 2
OMI_REVERSE_SCAN 1
OMI_UNREAD_ONLY 2
OMI_SMTP_POP_INTERFACE 3

Fichier Mail.kb

Fichier de la messagerie TSD Script

L'intégralité du fichier mail.kb se trouve dans le répertoire d'installation de la boîte à outils du développeur (Developer's Toolkit).


Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script

Retour à la table des matières

Copyright