Dialogue MAPI Windows

Doc mapi avec DhMapi.dll

La dll DhMapi permet d'envoyer par un programme DIVA des messages de type fax , mail ou e-mail.
Elle utilise la couche Mapi de Windows, les messages se retrouvent donc dans Exchange ou Outlook après l'envoi du message.
Le fichier include zmapi.dhsp contient les fonctions d'appel de la dll DhMapi et d'envoi de messages.
Le fichier mapisend.dhsp contient un exemple d'envoi de messages.
Le fichier mapiread.dhsp contient un exemple de lecture de messages.

1. Chargement de la dll
Le chargement de la dll se fait par la fonction MapiOpen , exemple :

2. Options de la dll
Puis il faut indiquer le profil à utiliser ainsi que certaines options.
L'appel à cette fonction est optionnelle, par défaut la dll prend le même paramétrage que DivaltoViewer ( voir choix Taille , choix Paramètres Envoyer ).
L'appel du profil et des options se fait par la fonction :
i = MapiOptions(profil,passe,afferr,dialog,retour)
Avec :

• profil : nom du profil à utiliser ou espace pour indiquer le profil par défaut.

• passe : mot de passe si le profil possède un mot de passe sinon espace.

• afferr : 1 - la dll mapi affiche les erreurs dans une boîte de dialogue.
  0 - c'est au programme DIVA d'afficher les erreurs.

• dialog : 1 - la dll affiche les boîtes de dialogues de connexion et d'envoi de

messages, l'utilisateur peut ainsi modifier le message.

• retour : 1 - avec accusé de réception
  0 - sans accusé de réception
  Exemple , options par défaut avec affichage des erreurs dans une boîte de dialogue :
  i = MapiOptions(" "," ",1,0,0)
  
  3. Envoi de message
  L'envoi de messages se fait par la fonction :
  i = MapiSend(type,sujet,texte,adresse,fichier)
  avec :

• type : type du message avec les valeurs suivantes :
  MAPI_FAX : fax
  MAPI_MAIL : mail
  MAPI_INTERNET : e-mail
  MAPI_AUTRE : autre adresse ( en fonction du paramétrage de xharview )
  MAPI_FAX2 : fax numéro 2 ( en fonction du paramétrage de xharview )
  MAPI_MAIL2 : mail numéro 2 ( en fonction du paramétrage de xharview )
  MAPI_INTERNET2 : e-mail numéro 2 ( en fonction du paramétrage de xharview )
  MAPI_AUTRE2 : autre adresse 2 ( en fonction du paramétrage de xharview )
  MAPI_DIRECT : l'adresse doit contenir le type de driver

• sujet : sujet du message , 255 caractères maximum

• texte : texte du message , 8191 caractères maximum
  Formatage du texte , passage à la ligne :
  
  cas 1:

• Le texte du message provient d'un rich-edit en mode texte : le texte contient déjà les
  codes de passage à la ligne , il n'y a rien à faire.
  cas 2:

• Le texte ne vient pas d'un rich-edit ou il est construit par programme : il ne contient
  pas les codes de passage à la ligne , il faut que le programme ajoute
  les codes $0d et $0a . exemple :
  1 mess 100
  mess = titre & $0d & $0a & ligne1 & $0d & $0a & ligne2
  cas 3:

• le texte ne vient pas d'un rich-edit ou il est construit par programme, mais on a prévu
  les passages à la ligne lors de la saisie du texte, il n'y a rien à faire.
  En effet xharmapi traduit le texte "\r" par $0d et "\n" par $0a automatiquement
  ( en fonction du paramétrage de xharview ). Il suffit de saisir par exemple
  "bonjour\r\nVeuillez trouver ci-joint etc " .
  Attention : si vous voulez écrire dans votre message le texte :
  "le fichier se trouve dans c:\har\sys"
  Il faut doubler le caractère "\" et écrire : "le fichier se trouve dans c:\har\sys"
  Le texte du message reçu par l'utilisateur sera bien : "le fichier se trouve dans c:\har\sys"

• adresse : adresse du destinataire du message.
  On peut mettre jusqu'à 32 adresses différentes mais de même type , il faut les séparer
  par le caractère ";" . Cette liste ne doit pas dépasser 2047 caractères au total .
  Exemples :

• fichier : liste de fichiers à joindre au message.
  On peut indiquer un ou plusieurs fichiers joints au message.
  On peut mettre jusqu'à 32 fichiers différents, il faut les séparer par le
  caractère ";" . Cette liste ne doit pas dépasser 2047 caractères au total .
  Attention : Les noms des fichiers sont au format Windows et non pas Divalto,
  il faut écrire par exemple "c:\divalto\sys\fichier" et non pas "/divalto/sys/fichier".
  Cas particulier : si vous mettez simplement le nom du "fichier" sans préciser son chemin ,
  DhMapi ira chercher ce fichier dans le répertoire /divalto/sys ( c'est à dire x:\divalto\sys ).
  Vous pouvez ainsi copier les fichiers à envoyer dans /divalto/sys et mettre simplement
  le nom du fichier dans la liste.
  exemple : copie du fichier /divalto/fic/vente dans /divalto/sys/mapivte puis mettre dans la liste
  des fichiers
  à envoyer : "mapivte; etc " .
  
  Exemples :

- Fichiers virtuels
On peut indiquer dans la zone des fichiers à joindre , le nom du "fichier virtuel" que Exchange ou Outlook utilisera et affichera dans le message Ce nom peut être fixe et est indépendant du nom du fichier réél.
Attention le nom de fichier virtuel doit obéir aux mêmes règles d'écriture que les noms de fichiers réels.
Exemple : dans DivaltoViewer l'aperçu est dans un fichier temporaire du style dvtr204a.tmp mais Exchange affiche toujours "Fichier joint.hvw".
Pour faire la même chose dans xharmapi.dll, il suffit d'ajouter "[nom du fichier virtuel]" après le nom du fichier réel à joindre, de plus ceci permet d'avoir un nom de fichier plus compréhensible que dvt204a.tmp
Exemples :

4. Fermeture
Enfin , après avoir envoyé un ou plusieurs messages , il faut décharger la dll par la fonction :
i = MapiClose

5. Liste des erreurs
Liste des erreurs mapi , la variable MapiTextError contient le texte de l'erreur
1 - L'utilisateur a annulé l'envoi de ce message.
2 - Erreur générale dans mapi32.dll
3 - Impossible d'ouvrir une session MAPI pour le profil x
4 - Disque plein
5 - Plus de mémoire disponible
6 - Accès refusé à MAPI
7 – ce numéro de code d'erreur n'est plus utilisé
8 - Trop de sessions MAPI en cours
9 - Trop de fichiers
10 - Trop de destinataires
11 - Fichier(s) attaché(s) à ce message non trouvé(s)
12 - Erreur à l'ouverture d'un fichier attaché à ce message
13 - Erreur en écriture dans un fichier attaché à ce message
14 - Destinataire x inconnu
15 - Type du destinataire x inconnu
16 - Il n'y a pas de message
17 - Message invalide
18 - Texte du message trop grand
19 - La session MAPI est invalide
20 - Type inconnu
21 - Destinataire x ambigu
22 - Message déjà en cours d'utilisation
23 - Erreur sur le réseau
24 - Champ d'édition invalide
25 - Destinataire x invalide
26 - Fonction non supportée dans cette version de MAPI

6. Exemples complets :

7. Cas particulier des fax
L'envoi d'un fichier par fax n'envoie pas les données du fichier mais l'impression de ce fichier sur une imprimante fax. L'envoi se fait selon la procédure suivante :
1) Lors de l'envoi d'un fichier par fax, Windows regarde l'extension du fichier.
2) Windows cherche alors un programme capable d'imprimer ce fichier dans la base de registre.
3) S'il trouve un programme, il le lance en lui demandant d'imprimer ce fichier sur l'imprimante fax.
Si Windows ne trouve pas de programme le fax sort en erreur.
Pour savoir si un type de fichier (en fonction des trois caractères de son extension) peut être envoyé par fax, il suffit de se positionner sur un fichier de même type avec l'explorateur de Windows et de cliquer sur le bouton droit. Si le choix "Imprimer" apparaît dans le menu popup, c'est qu'il existe un programme capable d'imprimer directement ce fichier . Ce type de fichier peut donc être envoyé par fax, sinon le fax sortira en erreur.

8. Fichiers DivaltoViewer
Les fichiers de DivaltoViewer (extension .dhvw) sont imprimés par DivaltoViewer.exe. S'il n'y pas le choix "Imprimer" dans le menu popup, c'est que DivaltoViewer n'est pas installé sur le disque. Il faut alors copier DivaltoViewer.exe et DhRtDivaCompr.dll dans le répertoire c:\divalto\sys, puis lancer DivaltoViewer.exe afin que celui-ci complète automatiquement la base de registre de Windows.

9. Lecture de la boîte de réception des messages de Mapi
Le programme MapiRead.dhsp permet de lire la boîte de réception des messages de mapi.
Il utilise la fonction d'ouverture de la boîte des messages :
i = MapiOpenMess
La lecture des messages se fait par la fonction :
i = MapiFindNextMess(ident)
La variable ident doit être une variable de 512 caractères que Mapi remplit avec une clé.
Cette clé permet d'identifier le message courant , il n'est valable que durant l'exécution du programme.
Puis , la lecture du message ce fait par la fonction :
i = MapiReadMess(ident,MAPI_PEEK )
On peut alors lire le contenu du message avec les fonctions :
i = MapiReadDateMess(buffer);message reçu le
i = MapiReadOrgineMess(name,name2,flags) ;envoyer par
i = MapiReadGetDestinatairesMess(nb);pour N destinataires

for j = 1 to nb
i = MapiReadDestinataireMess(name,name2,flags,j) ;noms des destinataires
next
i = MapiReadSujetMess(buffer);sujet du message
i = MapiReadTextMess(buffer);texte du message
i = MapiReadFlagsMess(flags);etat du message ,non lu,avec accusé de reception etc
i = MapiReadGetFilesMess(nb);nombre de fichiers joints
for j = 1 to nb
i = MapiReadFileMess(name,name2,flags,j);nom des fichiers joints
;la fonction readfichier(name) de l'exemple
;MapiRead.hsp permet de lire le contenu de
;chaque fichiers joints
next
if nb <> 0
i = MapiDeleteAttachMess;il faut supprimer les fichiers temporaires que Mapi
endif; à créer si le message contient des fichiers joints
On peut aussi modifier le message en cours ou le supprimer.
i = MapiSetSujetMess(buffer,mode) ;modification du sujet du message
i = MapiSetTextMess(buffer,mode) ;modification du texte du message
i = MapiReadFlagsMess(flags) ;modification des flags du message
i = MapiSaveMess(ident) ;sauvegarde du message en cours
i = MapiDeleteMess(ident) ;suppression du message
Puis il faut fermer la boîte de réception des messages de MAPI par la fonction :
i = MapiCloseMessMAPI

10. Convertion de fichierse en mode PDF
La DhMapi peut utiliser l'imprimante PDFMAIL pour convertir un fichier en mode PDF.
Il faut pour cela , d'abord installer le produit PDFMail de © RTE sur la machine .
La fc MapiTestSiConverPDF permet de savoir si cette fonctionnalité existe sur la machine .
Exemple de programme :