La programmation de CDO (1.21) et MAPI et CDO (2.0) pour Windows 2000 avec Microsoft Visual FoxPro.
Introduction. L’Idée de cet article est venue du fait que l’information sur CDO et MAPI est très difficile à obtenir et surtout pour les programmeurs FoxPro. Sur l’Internet il y a une certaine quantité d’articles et d’exemples de code pour les programmeurs de Visual Basic, mais pas beaucoup d’information pour les programmeurs FoxPro. L’article qui suit tente de créer une carte routière pour les programmeurs pour intégrer la messagerie dans leurs applications. La messagerie dans cet article réfère à la transmission d’informations en utilisant des moyens électroniques. CDO et MAPI sont des technologies puissantes qui fournissent l'infrastructure pour des applications sophistiquées de collaboration et de déroulement des opérations. Les applications Web peuvent aussi prendre avantage de la puissance et la flexibilité de MAPI et CDO. Microsoft fourni même une composante coté-serveur (CDO Rendering library) qui transforme le data de CDO en HTML prêt pour le browser Internet. Malheureusement la documentation pour cette technique (et autre) est très difficile à obtenir.
Cet article vise surtout les programmeurs FoxPro initiés qui on de l’expérience avec la programmation d’applications qui rencontrent de vrais exigences. Les programmeurs débutants seront probablement un peu perdus durant les référence techniques de CDO, COM et MAPI, mais ils peuvent toujours prendre avantage des exemples ci-inclus. L’article n’essaye pas de couvrir toutes les méthodes et propriétés de CDO, mais plutôt traite le sujet en assumant que le programmeur doit accomplir une tache spécifique et doit suivre une méthode logique du déroulement des concepts. MAPI Même si les lettres MAPI (Messaging Application Programming Interface) contiennent les lettres ‘API’ (Application programming interface), le concept des technologies est différent. MAPI utilise la technologie COM (Component Object Model) pour fournir une méthode de faire l’initialisation les objets de messagerie, qui en retour expose les méthodes qui peuvent être appelé pour agir sur ces dits objets. La structure MAPI. Les concepteurs de MAPI on reconnu que les applications de messagerie on certain dispositifs en commun et ces dispositifs peuvent être séparés en quatre composant distincts. Une interface (ou client) to présenter les objets à l’utilisateur. Un endroit pour emmagasiner les objets de la messagerie. Un fournisseur de transport, pour déplacer les messages d’endroit à un autre. Un carnet d’adresses, permettre le stockage, l’accès et la recherche d’adresses dans un dossier. Dépendant des besoins de l’application, il pourrait-y avoir une combinaison de un ou tous les composant mentionnés ci haut. Par exemple un utilisateur pourrait vouloir envoyer un message à plusieurs adresses, certains via courriel et certain via fax. Cet usager a donc besoins de deux sortes de fournisseur de transport. Un qui sait envoyer des messages courriels et un qui sait comment envoyer des messages via le fax. Et l’interface n’a pas besoin de savoir comment accomplir l’une ou l’autre de ces tâches. Anciennement, les applications de messagerie étant écrites de toutes pièces pour incorporer ces besoins dans une seule application. Le problème avec cette technique que l’usager qui envoie et celui qui reçoit doivent utiliser la même application, puisque la structure de messages doit rester constante. L’architecture de MAPI nous permet de se départir de ces restrictions. MAPI sépare les tâches en modules (comme expliqué ci haut), ce qui permet de créer un message sans être forcer d’utiliser un transporteur spécifique.
Les fournisseurs de services. Les fournisseurs de services sont la base du système de messagerie. Les applications utilisent ces fournisseurs pour créer, sauvegarder et rechercher des courriels. Il existe trois types de fournisseurs : Magasin de messages. Le fournisseur d’emmagasinage de messages et le lien entre le stockage d’information et le MAPI. Le format et la méthode de stockage n’a pas besoin d’être spécifié mais MAPI est assez flexible pour accommoder ce type de stockage. Transport. Le fournisseur de transport agit comme interface entre le mécanisme de transport et l’interface du client. Carnet d’adresse. Le fournisseur de carnet d’adresse agit comme interface entre une base de données d’information et l’interface du client. Les fournisseurs de service sont normalement fournis par l’application elle-même. Par exemple Microsoft Outlook ajoute un fournisseur de transport qui permet d’envoyer des courriels via l’Internet ou le fax. Une fois ces fournisseurs de transport sont installé sur un système, n’importe qu’elle application MAPI peut utiliser ces transporteurs. Par exemple, une application FoxPro peut automatiser Outlook pour utiliser le transporteur d’Outlook pour envoyer un courriel sans tout de même avoir besoin de montrer Outlook.
#DEFINE MAILITEM 0 #DEFINE IMPORTANCENORMAL 1 oOutLookObject = CreateObject("Outlook.Application") oEmailItem = oOutLookObject.CreateItem(MAILITEM) WITH oEmailItem .Recipients.Add("moe@3stooges.com") .Subject = "Automation sample" .Importance = IMPORTANCENORMAL .Body = "Essai de l’automatisation d’Outlook." .Send ENDWITH RELEASE oEmailItem RELEASE oOutLookObject
Note : Quand on écrit une application qui utilise MAPI (Que toutes les applications basées sur CDO utilisent) prenez note que les fournisseurs de services doivent exister sur le système de l’utilisateur. Application client. Un exemple d’application client qui permet d’utiliser un système de messagerie pourrait inclure: Système d’envoi de courriel, calendrier et gérance de contacts. Un ‘inbox’ qui permet d’effectuer les traitements additionnel sur les courriels qui entrent. Une section qui permet de créer et d’assigner des tâches. Une application qui gère des documents, qui ajoute l’option d’envoyer le document via courriel avec l’option d’envoyer placée directement dans le menu du document. Il y a plusieurs autres possibilités. L’élément commun ici est que les items sont manipulés et déménagés au nom d’un utilisateur, utilisant les différents fournisseurs de services comme stocker l’information, transporter les données et trouver les adresses requises pour envoyer les données. À noter qu’une application client comme décrite n’a pas besoin d’une interface. Le sous-système de MAPI. Le sous-système de MAPI est l’interface qui communique entre l’application client et les fournisseurs de services. Lorsqu’une application doit accéder à ces fournisseurs, l’application fait une requête au sous-système de MAPI. Et de là le sous-système de MAPI communique avec l’un de ces fournisseurs de services pour effectuer l’action requise. Le spooler de MAPI. Le Spooler MAPI fait partie du sous-système MAPI. La fonction principal du spooler est transporter le courriel que est prêt a partir vers un fournisseur de transport. Le spooler choisi le transporteur approprié dépendant du type d’adresse du message. Si le message contient plusieurs types d’adresses, le spooler fourni une copie du message à chaque transporteurs appropriés. Le spooler MAPI effectue aussi une vérification de l’adresse pour s’assurer du bon format. Les objets MAPI. MAPI est basé sur la technologie OOP. A partir de cette technologie, MAPI contient des structures pour représenter les messages, les dossiers, le carnet d’adresses, les récipiendaires etc. Chaque une ces structures contiennent des propriétés et des méthodes. Les technologies basées sur MAPI, comme CDO l’est, utilise les services MAPI pour accéder aux objets MAPI pour changer les propriétés et activer les méthodes. Les propriétés MAPI. Les propriétés représentent des données contenues par un objet. Un message courriel, par exemple, a une propriété ‘Sujet’ qui contient le sujet du message. Un message courriel a plusieurs propriétés. Les concepteurs de MAPI ont aussi conçu MAPI pour permettre qu’un programmeur puisse de lui-même ajouter des propriétés que les concepteurs n’ont pas prévues. L’ajout de ces propriétés faites sur mesure est disponible avec l’utilisation de CDO. La session MAPI. Une session est une période de temps pendant la quelle les services MAPI sont utilisés. Pour débuter une session, le client doit s’identifier avec un profil déjà existant. Une fois l’authentification approuvé, le client peut accéder les services MAPI. Une fois a fini d’utiliser les services, la session MAPI se termine. Notifications MAPI. Il existe un mécanisme de notification pour avertir l’usager que certains objets MAPI ont changé. Ces notifications pourraient par exemple avertir l’usager qu’un nouveau message est arrivé. Ces notifications ne sont pas accessibles avec FoxPro. Il y a des moyens avec FoxPro de contourner cette lacune, mais cette solution ne fais pas parti du sujet de cet article. Autres technologies de messagerie Common Messaging Calls (CMC) Le Common Messaging Calls est un API qui n’est pas dépendant d’une plateforme spécifique, qui est utilisé pour envoyer et recevoir des courriels. L’un des concepteurs de CMC est le groupe X.400 API Association, l’association qui est responsable pour la programmation de X.400. Le X.400 est un standard pour connecter des réseaux de courriels et connecter des usagers à ces réseaux de courriers. Le CMC un API qui n’est pas basée sur la plateforme Windows. Sur la plateforme Windows CMC accède aux mêmes propriétés MAPI que CDO. Le MAPI simple. Le MAPI simple est le précurseur de MAPI. Microsoft recommande de ne plus utiliser le simple MAPI mais plutôt d’utiliser les technologies de CMC, MAPI, l’Activex MAPI, CDO, CDO pour Windows 2000 ou CDO pour Exchange. L’Activex MAPI. Les programmeurs FoxPro sont normalement familier avec l’utilisation de contrôles Activex. L’Activex MAPI (mapi.session et mapi.messages) est basé sur le simple MAPI. Le programmeur FoxPro a seulement à ajouter le contrôle sur un formulaire et activer les propriétés de l’Activex. Étant basé sur le simple MAPI, l’Activex est sujet aux mêmes limitations que le simple Activex lui-même. CDO (1.21) Le CDO est basé sur le MAPI (ou Extended MAPI). Comme MAPI lui-même, CDO est un COM. Mais ce qui le différencie de MAPI, CDO est automatisable. CDO est riche en propriétés et méthodes, ce qui devrait guider le choix de tous développeurs FoxPro. CDO Rendering library. Cette librairie permet de montrer visuellement les objets de la messagerie (comme les dossiers et les courriels). Normalement utilisé sur un serveur Web et elle travaille en concert avec CDO. Librairie CDO pour NTS. Cette librairie est conçue spécifiquement pour être utilisé sur un serveur web NT. L’objet modèle d’Outllook. Cet objet est similaire à CDO. Il permet un véhicule pour automatiser MAPI. Pour des applications client le choix n’est pas clair entre CDO et le modèle Outlook. Pour ce qui est d’un serveur, CDO est nécessaire. Simple Mail Transport Protocol (SMTP). SMTP existe depuis longtemps et est le protocole qui transporte les courriels sur l’Internet. Il est possible avec le protocole SMTP d’éviter l’interface MAPI et d’utiliser directement les commandes SMTP. Par exemple en utilisant l’automation d’Outlook, dépendant de quelle mise à jour a été installée, un message demandant une confirmation d’envoi pourrait apparaître et donc enlevant l’aspect automatisation à l’application. En utilisant les commandes SMTP, ce message est évité, puisque les commandes sont envoyées directement au serveur SMTP. Mais, il faut aussi bien planifier, le SMTP par exemple ne peut envoyer des Fax. CDO pour Windows 2000. Anciennement connu sous CDO 2.0, est complètement différent du CDO original. Ce CDO, au lieu d’utiliser les propriétés et méthodes MAPI, il utilise les protocoles Internet. Donc le code écrit pour le CDO original ne fonctionnera pas avec le CDO pour Windows 2000, mais les deux versions peuvent co-exister dans une même application. CDO pour Exchange. CDO pour Exchange, parfois appelé CDO 3.0, est supposément la nouvelle génération de CDO. Il est écrit basé sur les protocoles Internet comme le CDO 2.0. Cet article ne couvre pas l’utilisation de CDO 3.0. Comment déterminer si MAPI est présent sur le système via programmation. Pour pouvoir utiliser MAPI (et CDO), MAPI doit entre présent sur le système. Il est possible via programmation de déterminer si MAPI est présent. La clef de registre pour le DLL MAPI est ‘HKEY_LOCAL_MACHINE\ SOFTWARE\Microsoft\Windows Messaging Subsystem.’ Il existe plusieurs méthodes pour accéder le registre et y lire leur valeurs. Voici un exemple qui utilise les appels API. Cet exemple devrait vous donner un curseur contenant les clefs et leurs valeurs. Il devrait lister les clefs suivantes : MAPIX ( MAPI - valeur 1 si installé), MAPI (Simple MAPI – valeur 1 si installé), CMC (CMC – valeur 1 si installé), OleMessaging (CDO – Valeur 1 si installé)
#Define ERROR_SUCCESS 0 #Define KEY_READ 131097 #Define KEY_ALL_ACCESS 983103 #Define HKEY_LOCAL_MACHINE 2147483650 && 0x80000002 Declare Integer RegCloseKey In advapi32 Integer hKey Declare Integer RegOpenKeyEx In advapi32; INTEGER hKey,; STRING lpSubKey,; INTEGER ulOptions,; INTEGER samDesired,; INTEGER @ phkResult Declare Integer RegEnumValue In advapi32; INTEGER hKey,; INTEGER dwIndex,; STRING @ lpValueName,; INTEGER @ lpcValueName,; INTEGER lpReserved,; INTEGER @ lpType,; STRING @ lpData,; INTEGER @ lpcbData hBaseKey = 0 lcBaseKey = "Software\Microsoft\Windows Messaging Subsystem" If RegOpenKeyEx (HKEY_LOCAL_MACHINE, lcBaseKey,; 0, KEY_ALL_ACCESS, @hBaseKey) <> ERROR_SUCCESS ? "Error opening registry key" Return Endif Create Cursor cs (valuename C(50), valuevalue C(200)) dwIndex = 0 Do While .T. lnValueLen = 250 lcValueName = Repli(Chr(0), lnValueLen) lnType = 0 lnDataLen = 250 cData = Repli(Chr(0), lnDataLen) lnResult = RegEnumValue (hBaseKey, dwIndex,; @lcValueName, @lnValueLen, 0,; @lnType, @lcData, @lnDataLen) f lnResult <> ERROR_SUCCESS Exit Endif lcValueName = Left (lcValueName, lnValueLen) lcData = Left (lcData, lnDataLen-1) Insert Into cs Values (lcValueName, lcData) dwIndex = dwIndex + 1 Enddo =RegCloseKey (hBaseKey) Select cs Index On valuename Tag valuename Go Top Browse Normal Nowait
Le Simple MAPI Vu que le simple MAPI n’est plus utilisé pour les applications modernes, il est préférable au lieu d’apprendre les appels API pour accéder au simple MAPI, d’utiliser la combinaison de ‘Miscrosoft MAPI messages Control’ et ‘Microsoft MAPI session control’. Voici un exemple de l’utilisation de ces deux Activex. Contrairement à certain Activex, la technique semble fonctionner par code seulement, sinon elle génère une erreur indiquant que le contrôle n’est pas enregistré. oform = CreateObject("form") oform.addobject("Session1","olecontrol","MSMAPI.mapiSession") oform.addobject("Message1","olecontrol","MSMAPI.mapiMessages") oform.Session1.signon oform.Message1.sessionid = oform.Session1.sessionid oform.Message1.compose oform.Message1.msgsubject = "Note de mon application FoxPro." oform.Message1.msgnotetext = "Ceci fonctionne!" oform.Message1.send(1) && Le paramètre 1 est requis pour envoyer le message. oform.Session1.signoff release oform
À titre d’exemple voici comment utiliser les appels API pour faire appel au simple MAPI. Le code suivant est gracieuseté d’Anatoliy Mogylevets de www.news2news.com/vfp.
#DEFINE MAPI_ORIG 0 #DEFINE MAPI_TO 1 #DEFINE MAPI_DIALOG 8 #DEFINE SUCCESS_SUCCESS 0 DO decl LOCAL hSession hSession = getNewSession() IF hSession = 0 ? "Unable to log on." RETURN ENDIF LOCAL loRcpEmail, loSndBuf, lcRcpBuf, loSubject, loNoteText,; loRcpBuf, lcMapiMessage, lnResult * populating message recipient, subject and body loRcpEmail = CreateObject ("PChar", "mgagnon@suntelecom.net") loSubject = CreateObject ("PChar", "W32: testing Simple MAPI") loNoteText = CreateObject ("PChar", "Test message.") * initializing buffer with single recipient data lcRcpBuf = num2dword(0) +; num2dword(MAPI_TO) +; num2dword(loRcpEmail.getAddr()) +; Repli(Chr(0), 12) loRcpBuf = CreateObject ("PChar", lcRcpBuf) * initializing buffer with sender data -- practically empty loSndBuf = CreateObject ("PChar", Repli(Chr(0), 24)) * merging all parts to a message buffer -- no file attachments lcMapiMessage = num2dword(0) +; num2dword(loSubject.getAddr()) +; num2dword(loNoteText.getAddr()) +; num2dword(0) + num2dword(0) + num2dword(0) + num2dword(0) +; num2dword(loSndBuf.getAddr()) +; num2dword(1) +; num2dword(loRcpBuf.getAddr()) +; num2dword(0) + num2dword(0) * sending the message with or without a confirmation dialog *lnResult = MAPISendMail(hSession, 0, @lcMapiMessage, MAPI_DIALOG, 0) lnResult = MAPISendMail(hSession, 0, @lcMapiMessage, 0, 0) IF lnResult <> SUCCESS_SUCCESS * 1 MAPI_E_USER_ABORT * 2 MAPI_E_FAILURE * 3 MAPI_E_LOGIN_FAILURE * 5 MAPI_E_INSUFFICIENT_MEMORY * 6 MAPI_E_ACCESS_DENIED * 9 MAPI_E_TOO_MANY_FILES *10 MAPI_E_TOO_MANY_RECIPIENTS *15 MAPI_E_BAD_RECIPTYPE *18 MAPI_E_TEXT_TOO_LARGE *14 MAPI_E_UNKNOWN_RECIPIENT * ... ? "Error returned:", lnResult ELSE ? "Sent initiated successfully!" ENDIF * closing current MAPI session = MAPILogoff (hSession, 0, 0, 0) FUNCTION getNewSession() * creates a new MAPI session and returns its handle #DEFINE MAPI_LOGON_UI 1 #DEFINE MAPI_NEW_SESSION 2 #DEFINE MAPI_USE_DEFAULT 64 #DEFINE MAPI_FORCE_DOWNLOAD 4096 && 0x1000 #DEFINE MAPI_PASSWORD_UI 131072 && 0x20000 LOCAL lnResult, lnSession, lcStoredPath lcStoredPath = SYS(5) + SYS(2003) lnSession = 0 lnResult = MAPILogon (0, "", "",; MAPI_USE_DEFAULT+MAPI_NEW_SESSION, 0, @lnSession) * sometimes you need to restore default path - Outlook Express SET DEFAULT TO (lcStoredPath) RETURN Iif(lnResult=SUCCESS_SUCCESS, lnSession, 0) FUNCTION num2dword (lnValue) #DEFINE m0 256 #DEFINE m1 65536 #DEFINE m2 16777216 LOCAL b0, b1, b2, b3 b3 = Int(lnValue/m2) b2 = Int((lnValue - b3*m2)/m1) b1 = Int((lnValue - b3*m2 - b2*m1)/m0) b0 = Mod(lnValue, m0) RETURN Chr(b0)+Chr(b1)+Chr(b2)+Chr(b3) *| for some structures you need not just strings but pointers to strings *| to be assigned to structure fields; *| this class implements such "dual" strings DEFINE CLASS PChar As Custom PROTECTED hMem PROCEDURE Init (lcString) THIS.hMem = 0 THIS.setValue (lcString) PROCEDURE Destroy THIS.ReleaseString FUNCTION getAddr && returns a pointer to the string RETURN THIS.hMem FUNCTION getValue && returns string value LOCAL lnSize, lcBuffer lnSize = THIS.getAllocSize() lcBuffer = SPACE(lnSize) IF THIS.hMem <> 0 DECLARE RtlMoveMemory IN kernel32 As Heap2Str; STRING @, INTEGER, INTEGER = Heap2Str (@lcBuffer, THIS.hMem, lnSize) ENDIF RETURN lcBuffer FUNCTION getAllocSize && returns allocated memory size (string length) DECLARE INTEGER GlobalSize IN kernel32 INTEGER hMem RETURN Iif(THIS.hMem=0, 0, GlobalSize(THIS.hMem)) PROCEDURE setValue (lcString) && assigns new string value #DEFINE GMEM_FIXED 0 THIS.ReleaseString DECLARE INTEGER GlobalAlloc IN kernel32 INTEGER, INTEGER DECLARE RtlMoveMemory IN kernel32 As Str2Heap; INTEGER, STRING @, INTEGER LOCAL lnSize lcString = lcString + Chr(0) lnSize = Len(lcString) THIS.hMem = GlobalAlloc (GMEM_FIXED, lnSize) IF THIS.hMem <> 0 = Str2Heap (THIS.hMem, @lcString, lnSize) ENDIF PROCEDURE ReleaseString && releases allocated memory IF THIS.hMem <> 0 DECLARE INTEGER GlobalFree IN kernel32 INTEGER = GlobalFree (THIS.hMem) THIS.hMem = 0 ENDIF ENDDEFINE PROCEDURE decl DECLARE INTEGER MAPILogon IN mapi32; INTEGER ulUIParam, STRING lpszProfileName,; STRING lpszPassword, INTEGER flFlags,; INTEGER ulReserved, INTEGER @lplhSession DECLARE INTEGER MAPILogoff IN mapi32; INTEGER lhSession, INTEGER ulUIParam,; INTEGER flFlags, INTEGER ulReserved DECLARE INTEGER MAPISendMail IN mapi32; INTEGER lhSession, INTEGER ulUIParam, STRING @lpMessage,; INTEGER flFlags, INTEGER ulReserved
Il est aussi possible de lire les courriels avec des appels API vers le simple MAPI. Ceci inclus l’API MAPIReadMail : DECLARE INTEGER MAPIReadMail IN mapi32; INTEGER lhSession, INTEGER ulUIParam,; STRING lpszMessageID, INTEGER flFlags,; INTEGER ulReserved, INTEGER @lppMessage
CDO (1.21) Créer une application en utilisant CDO et MAPI. Cette section de l’article vous montre comment créer une simple application pour envoyer et recevoir des courriels en utilisant CDO. Le code est divisé en sept modules : · Les globales. La déclaration de la session MAPI et quelques fonctions principales · Un formulaire qui présente une interface similaire à Windows Explorer. · Un formulaire qui permet d’ouvrir un message, le lire et sauvegarder un attachement. · Un formulaire pour composer un nouveau message. · Un formulaire pour aller chercher un attachement.
Etablir une session. Pour établir une session il faut déclarer une session MAPI et se faire authentifier. Local oSession oSession = createobject(‘mapi.session’) oSession.logon(‘Outlook’) && Peut varier et peut requérir un mot de passe.
Les paramètres de la méthode logon sont : Profilename : Le nom du profile à utiliser pour la session MAPI. Si le paramètre est vide, un boite de dialogue va apparaître, qui permet d’utiliser un profile déjà existant, ou d’en créer un nouveau. ProfilePassword : Si nécessaire ce paramètre doit contenir le mot de passe du profile. ShowDialog : Une valeur (.T. ou .F.) qui détermine comment MAPI va réagir si le paramètre ProfileName est vide. Si le ProfileName est vide, MAPI met ce paremetre à .T. et le dialogue apparaît. Si ce paramètre est à .F. et le ProfileName est vide, un erreur CdoE_LOGON_FAILED est généré. Si le Profilename contient une valeur et que le ShowDialog est à .T. , le dialogue est ignoré. NewSession : Une valeur (.T. ou .F.) qui détermine si MAPI doit créer une nouvelle session ou utiliser une session existante. ParentWindow : Un variable qui contient le hWnd de la fenêtre principale de votre application, pour rendre celle-ci la fenêtre parent. NoMail : Une Valeur (.T. ou .F.), qui détermine si le spooler MAPI doit ou ne doit pas vérifier la présence de nouveau courriel. ProfileInfo : Ce paramètre est utilisé pour créer un profile temporaire, mais seulement dans le cas de Microsoft Exchange. Les erreurs. Le code utilisé pour créer la session doit être capable de gérer les erreurs. CdoE_USER_CANCEL : Cette erreur est générée lorsque l’utilisateur décide de canceller le dialogue d’authentification. CdoE_LOGON_FAILED : Cette erreur est générée lorsque CDO ne peut établir une session MAPI. Le problème peut-être une mauvaise configuration de MAPI ou MAPI n’existe pas sur le système ou un mauvais paramètre a été envoyé au MAPI. Envoyer un courriel. 1. Une fois que l’application a établi une session avec succès, elle peut envoyer un courriel. Envoyer un simple courriel est très facile. Envoyer un courriel avec attachement et Rich Text est discuté plus loin dans cet article. Voici comment envoyer un simple courriel.
oSession = CreateObject("MAPI.Session") oSession.Logon("Outlook") oNouveauMessage=oSession.Outbox.messages.add() oNouveauMessage.Subject = "Comment envoyer un message avec CDO." oNouveauMessage.Text = "Bienvenue au monde de CDO" oNouveauMessage.DeliveryReceipt = .T. && Optionnel, CDO va retourner un message une fois le courriel lu par le récipiendaire. oRecipient = oNouveauMessage.Recipients.Add() oRecipient.Name = "Mike Gagnon" && Ce nom doit apparaître dans le carnet d’adresses. oRecipient.Resolve && Si le récipiendaire n’existe pas, ceci va générer une erreur oNouveauMessage.Update() && Mis a jour du message oNouveauMessage.Send(1,0,0) && Le paramètre 1 va garder une copie du message dans la boite Sent Items. oSession.Logoff() 2. A noter que les paramètres pour la méthode Add() sont comme suit (Ou il peuvent être spécifier un à un comme l’exemple ci haut) : oNouveauMessage = oSession.Outbox.messages.add([Subject],[Text],[Type],[Importance]) Subject: Ceci est un paramètre optionnel lors de la création d’un nouveau message. Il peut contenir le sujet du courriel. Ce paramètre est vide par défaut. Text : Ceci est un paramètre optionnel lors de la création d’un nouveau message. Il peut contenir le corps du nouveau message courriel. Par défaut il est vide. Type : Ceci est un paramètre optionnel lors de la création d’un nouveau message. Il peut contenir le type de message envoyé. Par défaut le valeur est ‘IPM.note’ (un message courriel. Importance : Ceci est un paramètre optionnel. Il peut contenir le niveau d’importance d’un nouveau message courriel.
A noter qu’il n’y a aucune avantage technique d’utiliser ces quatre paramètres, plutôt que de les spécifier un à un à la création d’un message.
3. Pour régler les propriétés d’un nouveau si les paramètres ci haut sont laissés vides. . A noter aussi que si le nom du récipiendaire apparaît plus d’une fois, une boite de dialogue va ouvrir pour permettre à l’utilisateur d’en choisir un.
La liste complète de tous les paramètres de MAPI peut trouvés dans l’appendice A ci-joint.
DeliveryReceipt : Valeur .T. ou .F. (La valeur par défaut est .F.). Indique qu’un message de notification sera retourné à l’expéditeur une fois le courriel arrive à sa destination. Importance : Indique le niveau d’importance que l’expéditeur peut assigner au message. Ces valeurs peuvent être réglées avec CdoNormal, CdoLow et CdoHigh. La valeur par défaut est CdoNormal. #DEFINE CdoLow 0 && Low importance #DEFINE CdoNormal 1 && Normal importance #DEFINE CdoHigh 2 && High importance ReadReceipt: Valeur .T. ou .F.. Indique qu’une notification sera retournée, une fois que le récipiendaire aura lu le message. La valeur par défaut est .F.. Sensitivity : Signifie le degré de sensibilité assigné au message. Les différents degrés sont : CdoNoSensitivity, CdoPersonal, CdoPrivate ou CdoConfidential. #DEFINE CdoNoSensitivity 0 && Normal sensitivity #DEFINE CdoPersonal 1 && Personal sensitivity #DEFINE CdoPrivate 2 && Private sensitivity #DEFINE CdoConfidential 3 && Confidential sensitivity Subject: Contient le sujet du message. Par défaut cette propriété est vide. Text : Contient le corps du message. Par défaut cette propriété est vide. Type : Spécifie le type de message envoyé, comme un courriel, une tâche, un rendez-vous, un contact etc. La valeur par défaut est ‘IPM.Note’ (courriel).
Pour chaque récipiendaire. Pour ajouter un récipiendaire la syntaxe est: oRecipient = oNouveauMessage.Recipients.Add([Name],[Address],[Type],[EntryID])
Name: Permet de mettre le nom du récipiendaire. Ce paramètre est ignoré si EntryID est fourni. Cette propriété est vide par défaut. Le nom doit être utilisé comme il apparaît dans le carnet d’adresse. Address : Permet de spécifier l’adresse du récipiendaire. Ce paramètre est ignoré si EntryID est fourni. Cette propriété est vide par défaut. Type : Permet de spécifier le type de récipiendaire. La valeur par défaut est CdoTo. #DEFINE CdoTo 1 && Primary recipient #DEFINE CdoCc 2 && CC to recipient #DEFINE CdoBcc 3 && BCC to recipient EntryID: Permet d’utiliser le numéro d’identification d’un récipiendaire.
La méthode Resolve permet à MAPI de vérifier si le nom du récipiendaire existe dans le carnet d’adresse. Un paramètre existe pour Resolve qui permet de montrer la boite de dialogue pour confirmer le nom. oRecipient.Resolve(.t.) && Montre la boite dialogue.
La méthode Send() d’un message. Il existe 3 paramètres pour la méthode Send(). oNouveauMessage.Send([SaveCopy],[ShowDialog],[ParentWindow])
SaveCopy: Ce paramètre indique si une copie du message sera sauvegardée dans le dossier SentItems. La valeur par défaut est .F. (0). ShowDialog : Ce paramètre permet de montrer la boite de dialogue de la progression de l’envoi. Par défaut ce paramètre est .F. (0). ParentWindow : Permet de spécifier le hWnd de la fenêtre parent, pour faire apparaître le ShowDialog dans la fenêtre parent.
4.4 Envoyer un courriel avec attachement.
MAPI défini 4 type d’attachements. Un fichier, une référence à un fichier, un objet OLE et un message incorporé. CDO peut gérer ces quatre types d’attachements. Pour ajouter un attachement à un message, utilisez la méthode Attachements.
oNouveauMessage.Attachments.Add([Name],[Position],[Type],[Source]) Name: Permet d’indiquer le nom de l’attachement comme il va apparaître lors de la réception du message. Position : Signifie la position que va prendre l’attachement dans le message. Il est à noter que certaines applications de courriel ignorent ce paramètre. Donc si l’on mesure la longueur de la propriété Text du message et on ajoute un 1, l’attachement devrai se positionner après le Text du message. Type : Signifie le type d’attachement inclus dans le message. #DEFINE CdoFileData 1 && Message has embedded file #DEFINE CdoFileLink 2 && Message has link to the file #DEFINE CdoOle 3 && Message contains OLE object #DEFINE CdoEmbeddedMessage 4 && Message contains Message
CdoFileData requiert le chemin complet du fichier. ‘C:\Mes Document\Monfichier.txt’ CdoFileLink Permet l’utilisation de la convention UNC (Universal Naming Convention), par exemple : ‘\\mikeg\mes documents\dépenses mensuelles.xls’ CdoOle Spécifier le chemin complet du fichier OLE. Exemple : ‘C:\Mes Document\Monfichier.xls’ CdoEmbeddedMessage Spécifier un identificateur unique pour le message incorporé.
Envoyer une référence à un fichier. #Define CdoFileData 1 && ReadFromFile method Attachment is a file (Default value) #Define CdoDefaultFolderOutbox 2 oSession = Createobject('MAPI.Session') oSession.Logon('Microsoft Outlook Internet Settings','') oFolder=oSession.GetDefaultFolder(CdoDefaultFolderOutbox) oMessage=oFolder.Messages.Add() oAttachment = oMessage.Attachments.Add( 'autoexec.bat',1,CdoFileData,'c:\autoexec.bat') oAttachment.ReadFromFile( 'c:\autoexec.bat') oMessage.Update() oMessage.Send() oSession.LogOff
Envoyer un objet OLE.
MAPI permet d’envoyer un document compris à l’intérieur d’un autre document. Ce document doit être un document OLE (ex : Un document Word, Excel etc.) Réglez le paramètre Type à CdoOle. Réglez le paramètre Source avec le chemin complet et le nom du fichier. Réglez le paramètre Position à la position désiré pour l’attachement apparaisse dans le message. Laissez le paramètre Name vide, ou omettre le paramètre.
Voici un exemple :
#DEFINE CdoOle 3 && Message contains OLE object #Define CdoDefaultFolderOutbox 2 oSession = Createobject('MAPI.Session') oSession.Logon('Microsoft Outlook Internet Settings','') oFolder=oSession.GetDefaultFolder(CdoDefaultFolderOutbox) oMessage=oFolder.Messages.Add() oAttachment = oMessage.Attachments.Add( ‘’,1,CdoOle,'c:\monfichier.xls') oMessage.Update() oMessage.Send() oSession.LogOff
Envoyer un message incorporé.
La différence principale avec cette technique est que l’attachement apparait dans le message comme un icône à l’intérieur du message.
Voici un exemple : #DEFINE CdoEmbeddedMessage 4#Define CdoDefaultFolderOutbox 2 oSession = Createobject('MAPI.Session') oSession.Logon('Outlook') oFolder=oSession.GetDefaultFolder(CdoDefaultFolderOutbox) oMessage=oFolder.Messages.Add() oAttachment = oMessage.Attachments.Add( ‘Fichier inclus’,1, CdoEmbeddedMessage,'c:\monfichier.txt') oMessage.Update() oMessage.Send() oSession.LogOff
Lire les courriels
En assument qu’une session MAPI a été établie avec succès. Lire un courriel comprend deux fonctions principales :
Atteindre le dossier que contiennent les messages dans la hiérarchie des objets CDO. La lecture des propriétés du message pour y retirer l’information du message.
Exemple d’un Treeview qui contient les dossiers Outlook. PUBLIC oform1 oform1=NEWOBJECT("form1") oform1.Show RETURN DEFINE CLASS form1 AS form DoCreate = .T. AutoCenter = .T. Caption = "Dossiers Outlook" Name = "Form1" MinButton = .f. maxbutton = .f. ADD OBJECT oletv AS olecontrol WITH ; Top = 12, ; Left = 36, ; Height = 193, ; Width = 289, ; Name = "OLETV", ; OleClass = "MSComctlLib.TreeCtrl.2" PROCEDURE Init LOCAL oSession,loFolders,loFolder o = CREATEOBJECT('mapi.session') o.Logon('outlook') mondossier=o.InfoStores(1).rootfolder FOR EACH dossier IN mondossier.folders thisform.oleTV.Nodes.Add(,1,SYS(2015),dossier.name,,) ENDFOR ENDPROC ENDDEFINE
Exemple d’un Treeview qui contient tous les messages dans le Inbox de Outlook. PUBLIC oform1 oform1=NEWOBJECT("form1") oform1.Show RETURN DEFINE CLASS form1 AS form Height = 250 Width = 535 DoCreate = .T. AutoCenter = .T. Caption = "Messages dans le Inbox" Name = "Form1" ADD OBJECT oletv AS olecontrol WITH ; Top = 12, ; Left = 36, ; Height = 193, ; Width = 456, ; Name = "OLETV", ; OleClass = "MSComctlLib.TreeCtrl.2" PROCEDURE Init Local oSession,loFolders,loFolder o = Createobject('mapi.session') o.Logon('outlook') mondossier=o.InfoStores(1).rootfolder For Each dossier In mondossier.folders IF Dossier.name ="Inbox" FOR EACH message IN dossier.messages thisform.oleTV.Nodes.Add(,1,SYS(2015),message.subject,,) endfor endif Endfor ENDPROC ENDDEFINE
Le carnet d’adresses.
Exemple pour montrer le carnet d’adresses.
o = Createobject(‘mapi.session’) o.logon(‘Outlook’) o.AddressBook([Recipients],[Title],[OneAddress],[ForceResolution],[RecipLists],[ToLabel],[CcLabel],[BccLabel],[ParentWindow])
Recipients: Une collection de récipiendaires qui peut-être spécifié au lieu de montrer toutes le adresses dans le carnet. Title : Une propriété pour spécifier le titre de la boite de dialogue. OneAddress : Valeur .T. ou .F.. Spécifie si l’usager peut sélectionner une seule adresse ou en sélectionner plusieurs à la fois (multi-select). La valeur par défaut est .F.. ForceResolution : Si ce paramètre est mis à .T., le carnet d’adresse essaye de resoudre le nom choisi avant de retourner. RecipLists : Ce paramètre permet d’ajouter les champs Cc et Bcc au bas de la boite de dialogue. Le paramètre 1 équivaut à montrer seulement le destinataire, le paramètre 2 montre le destinataire (to) et le CC. Le paramètre 3 montre le destinataire, le CC et le BCC. ToLabel,CcLabel,BccLabel : Ces trois paramètres permettent de changer les captions des trois champs ci-haut mentionnés. ParentWindow : Ce paramètre permet de spécifier le hWnd de la fenêtre parent.
Note : Il y a plusieurs autres modules de MAPI que cet article ne traite pas, mais sont tout aussi accessibles. Le calendrier, les tâches, les rendez-vous, contacts etc. Peut-être le sujet d’un autre article. Il est donc possible avec CDO, MAPI et Visual Foxpro de construire une application complète qui peut gérer le courriel.
CDO pour Windows 2000 (2.0)
Avec l’arrivée de CDO pour Windows 2000, CDO se passe des propriétés et méthodes de MAPI mais plutôt il utilise les protocoles Internet. Donc le code écrit pour CDO 1.21 ne fonctionnera pas pour CDO 2.0.
Les propriétés du message CDO 2.0
Attachments : Propriété en lecture seule. Une propriété que représentent les attachements d’un courriel. AutoGenerateTextBody : Valeur .T. ou .F.. Cette valeur indique si la propriété devra être réglée automatiquement basé sur le valeur de la propriété HTMLBody. BCC : La propriété qui contient (les) adresse(s) qui n’apparaîtrons pas au autres récipiendaires (Blind Copy) BodyPart : Une référence qui émane de IBodyPart. Cette propriété contient la partie racine d’un message à plusieurs parties. Cette propriété n’est pas utilisé lorsque le message a seulement une partie. CC : Propriété qui contient les récipiendaires visible du message, Configuration : Retourne le réglage de la configuration du message. Chaque message a sa propre configuration. Si vous voulez changer cette configuration, créer un instance de la configuration et effectuer les changements requis. DataSource : Contient la référence aux objets contenus dans un message. DNSOptions : Spécifie le réglage de l’option de notification. Les valeurs peuvent être : 0 – cdoDNSDefault = aucune notification requise 1 – cdoDNSNever = aucune notification requise. 2 – cdoDNSFailure = notification d’un message non livrable. 4 – cdoDNSSuccess = notification d’un message livré. 8 – cdoDNSDelay = notification d’un message avec délai. 14 – cdoDNSSuccessFailOrDelay = notification des trois résultats. EnvelopeFields : Lecture seule. Cette propriété est utilisée avec la synchronisation du transport. Fields : Lecture seule.Contient la collection des champs de l’objet message. FollowUpTo : Contient le nom du newsgroup qui devrait répondre à ce message. From : La propriété que contient le (ou les) auteurs du message. Si cette valeur est laissé vide, la propriété Sender est retenue. HTMLBody : La propriété qui contient la version HTML du message, Vide par défaut. HTMLBodyPart : Lecture seule. Une référence qui émane de IBodyPart qui représente la version HTML du message. KeyWords : Propriété qui contient des mots clefs (séparé par des virgules). Peut-être utilisé par les récipiendaires si le message a de l’intérêt, MDNRquested : (Message Disposition Notification). Valeur .T. ou .F.. (Valeur par défaut .F.) MimeFormatted : Valeur .T. ou .F.. Détermine si le message est formaté en MIME (Mutltipurpose Internet Mail Extensions) ou UUENCODE. NewsGroups : Propriété qui contient le nom des newsgroups de ce message (séparé par des virgules). Valeur par défaut est vide. Organizations : Contient le nom de l’organisation de l’expéditeur, pour faire apparaître lors des postes sur les newsgroups. ReceivedTime : Lecture seule. Contient la date et l’heure que le message a été reçu par le serveur. ReplyTo : Contient l’adresse à laquelle la réponse du message devrait être adressée. Sender : Contient le nom qui va apparaître comme expéditeur (style ‘de la part de :’ (Si différent de la Propriété From ou s’il y a plusieurs expéditeurs. SentOn : Lecture seule. Contient la date et l’heure que le message a été envoyé. Subject : Contient le sujet du message. TextBody : Contient la version texte du message. TextBodyPart : Lecture seule. Une référence qui émane de IBodyPart qui représente la version texte du message. To : Contient les récipiendaires principaux du message.
Les méthodes du message. AddAttachement : Ajoute un attachement au message. La syntaxe est : oCDO2 = createobject(‘cdo.message’) oCDO2.AddAttachement([URL],[UserName],[Password])
URL: Contient le chemin du fichier à être attaché. Les préfixes supporté sont file://, ftp://, http:// et https://. Le préfixe par défaut est file://, donc les chemin standard des fichiers peut-être utilisé. UserName : Optionnel. Permet de d’envoyer un nom d’utilisateur (si il est requis) lorsque le fichier parvient de transporteur HyperText Transport Protocol. Password : Optionnel. Associé au paramètre UserName ci haut.
AddRelatedBodyPart : Fait référence à un lien dans la portion HTML du message à un objet qui doit être inclus dans le message. Par exemple un message en HTML peut faire référence à un image qui fait partie du texte HTML. La syntaxe est : oCDO2.AddRelatedBodyPart([URL],[Reference],[ReferenceType],[UserName],[Password])
URL: Contient le chemin du fichier à être attaché. Les préfixes supporté sont file://, ftp://, http:// et https://. Le préfixe par défaut est file://, donc les chemins standard des fichiers peut-être utilisé. Reference : Contient les ressources, qui a le but de joindre la référence à la section HTML du message ReferenceType : Une valeur qui indique la sorte de donnée utilisé dans la référence ci haut. UserName : Optionnel. Permet de d’envoyer un nom d’utilisateur (si il est requis) lorsque le fichier parvient de transporteur HyperText Transport Protocol. Password : Optionnel. Associé au paramètre UserName ci haut.
CreateMHTMLBody : Méthode qui converti le contenu du page Web en un message multiple portions. Les images et autres objets liés sont inclus dans le message. La fonction n’est pas récursive, si les liens contiennent des liens eux-mêmes ils sont ignorés. La syntaxe est : oCDO2.CreateMHTMLBody([URL],[Flags],[Username],[Password])
URL: Contient le chemin du fichier à être attaché. Les préfixes supporté sont file://, ftp://, http:// et https://. Le préfixe par défaut est file://, donc les chemins standard des fichiers peut-être utilisé. Flags : Une valeur qui détermine combien d’information va suivre le message. Ces valeurs peuvent ëtre combinées en additionnant leur valeurs numériques. #DEFINE cdoSuppressNone 0 && Download all resources referred to in elements within the resource at the specified URI (not recursive). #DEFINE cdoSuppressImages 1 && Do not download resources referred to in IMG elements. #DEFINE cdoSuppressBGSounds 2 && Do not download resources referred to in BGSOUND elements. #DEFINE cdoSuppressFrames 4 && Do not download resources referred to in FRAME elements. #DEFINE cdoSuppressObjects 8 && Do not download resources referred to in OBJECT elements. #DEFINE cdoSuppressStyleSheets 16 && Do not download resources referred to in LINK elements. #DEFINE cdoSuppressAll 31 && Do not download any resources referred to from within the page.
UserName : Optionnel. Permet de d’envoyer un nom d’utilisateur (si il est requis) lorsque le fichier parvient de transporteur HyperText Transport Protocol. Password : Optionnel. Associé au paramètre UserName ci haut.
Forward : Crée un nouveau message pour faire suivre le message original. oCDO2.Forward()
GetInterface : Procure une autre façon d’obtenir les valeurs des propriétés BodyPart et DataSource. oCDO2.GetInterface(interface) && Valeurs possibles de interface sont :IBodyPart et IDataSource.
GetStream : Retourne le message complet dans un Stream ADO. oCDO2.GetStream()
Post : Poster le message sur le newsgroup spécifié dans la propriété NewsGroup. oCDO2.Post()
PostReply : Crée un nouveau message pour être utilisé pour poster une réponse sur un newsgroup oCDO2.PostReply().
Reply : Crée un nouveau message qui va être utilisé pour répondre à un autre message. oCDO2.Reply() ReplyAll : Crée un nouveau message pour être utiliser pour répondre à l’expéditeur et tous le récipiendaires contenu dans la propriété CC. oCDO2.ReplyAll() Send : Envoie le message. oCDO2.Send()
Envoyer un courriel.
Il y a deux façons principales d’envoyer un courriel avec CDO 2.0. Le premier est de créer un message et de l’envoyer directement sans passer par un serveur SMTP et l’autre est de passer par un serveur SMTP (ou le service SMTP de Microsoft).
Envoyer un simple courriel sans passer par SMTP.
Courriel en format texte. Local oCDO2 oCDO2 = createobject(‘cdo.message’) With oCDO2 .Subject = ‘Mon sujet’ .From = ‘Mike Gagnon’ && De la part de. .To = ‘toi@quelquepart.net’ .Sender =’moi@quelquepart.com’ .TextBody=’Voici le texte du message’ Endwith oCDO2.send()
Courriel en format HTML Local oCDO2 oCDO2 = createobject(‘cdo.message’) With oCDO2 .Subject = ‘Mon sujet’ .From = ‘Mike Gagnon’ && De la part de. .To = ‘toi@quelquepart.net’ .Sender =’moi@quelquepart.com’ .HTMLBody=’Voici le texte du message’ Endwith oCDO2.send()
A noter que d’après mon expérience la Propriété From peut-être vide, mais non la propriété Sender. D’après mes tests, l’adresse Sender n’est pas forcément obligée d’être une adresse valide, elle peut même contenir un seul caractère. A noter que laisser les propriétés From et Sender cause une erreur.
Envoyer un courriel en passant par un serveur SMTP.
iMsg = Createobject("CDO.Message") iConf = Createobject("CDO.Configuration") Flds = iConf.Fields With Flds .Item("http://schemas.microsoft.com/cdo/configuration/sendusing") = 2 .Item("http://schemas.microsoft.com/cdo/configuration/smtpserver") = 'Votre serveur SMTP ' .Item("http://schemas.microsoft.com/cdo/configuration/smtpserverport") = 25 .Item ("http://schemas.microsoft.com/cdo/configuration/smtpauthenticate") = cdoBasic
.Item("http://schemas.microsoft.com/cdo/configuration/sendusername") = "youruserid" .Item("http://schemas.microsoft.com/cdo/configuration/sendpassword") = "yourpassword"
.Item("http://schemas.microsoft.com/cdo/configuration/smtpusessl") = .F.
.Item ("http://schemas.microsoft.com/cdo/configuration/smtpconnectiontimeout") = 60
.Update Endwith With iMsg .Configuration = iConf .To = "me@hotmail.com" .CC = "" .BCC = "" .From = "me@somewhere.com" .Subject = "Ceci est un essaye" .TextBody = "Le corps du message" .Send() Endwith iMsg = .Null. iConf = .Null. wb = .Null.
Conclusions.
Cet article traite principalement deux méthodes d’envoyer des courriels (CDO 1.21 avec MAPI et CDO 2.0). Il existe plusieurs autres méthodes pour envoyer des courriels avec Visual FoxPro qui ne sont pas traitées. La différence que je remarque entre CDO 1.21 et CDO2.0 est qu’avec CDO 1.21 il est possible de construire une application complète avec interface (mais est limité par la version d’Outlook qui peu générer un message qui requiert l’autorisation de l’utilisateur d’envoyer le courriel) et que CDO 2.0 est plutôt à être utilisé en tant que service (sans interface) ou en conjonction avec Microsoft Exchange (qui fourni l’interface). A vous de choisir le procédé qui rempli votre demande.
Bibliographie et références.
1. Introduction to Collaboration Data Objects http://www.microsoft.com/technet/prodtechnol/exchange/55/deploy/cdofinal.mspx 2. www.cdolive.com 3. Microsoft Collaboration data objects 2.0 http://support.microsoft.com/ph/6384 4. CDO & MAPI programming by Dave GrunGeiger. 5. www.news2news.com/vfp
| 
Retour à la liste
Canada
Fiche personnelle
Note des membres
Mike, j'ai juste un pb avec le code de lecture des emails ! Peut être est-ce du au fait que je n'ai qu'outlook express sur ma machine !?!
Il me dit mapi.session introuvable ( remplacé par MSMAPI.MAPISESSION -> la c'est ok,
puis erreur objet introuvable avec o.logon('outlook')
tu peux me dire comment on peux faire ?
sinon c'est du bon boulot !