Composant SYSMAIL

Généralités

L'objet INTERFACE du composant SYSMAIL contient des méthodes permettant d'envoyer des courriers électroniques ou e-mails.

Il contient également une méthode permettant de personnaliser des fichiers en remplaçant des jetons par des données. Voir la méthode TRANSFORMER.

Enfin il contient des méthodes pour faire des petits transferts FTP / HTTP.

Deux moyens techniques sont à dispositions :

1. Simple MAPI

MAPI permet d'envoyer des e-mails en utilisant le logiciel de messagerie par défaut. Les e-mails envoyés avec MAPI seront stockés dans les "Eléments envoyés" du logiciel de messagerie.

Simple MAPI est limité dans les options d'envoi : pas de texte riche dans le corps de l'e-mail, pas d'accusé de réception (dépend du logiciel) ...

La version "Simple" de MAPI est un sous ensemble de fonctions basiques de MAPI (Extended).

Remarque : par souci de sécurité, certains logiciels peuvent afficher un message demandant confirmation avant l'envoi si l'email n'a pas été affiché à l'écran par la messagerie. (Utiliser la valeur 8 du paramètre flags de la méthode  NOUVELLE_SESSION_SIMPLE_MAPI).

2. SMTP

L'utilisation du protocole SMTP permet de communiquer directement avec le serveur de courrier. Cela est plus rapide et autorise toutes les options.

Mais attention car il faut absolument connaître l'adresse du serveur SMTP (ainsi que le port utilisé si ce n'est pas celui par défaut).

Principe d'utilisation du composant

Pour envoyer un message, il vous faut utiliser plusieurs méthodes du composant.

Vous devez :

• créer une session suivant votre choix de technologie (SMTP ou MAPI)

• créer un nouveau message : un ID est attribué au message pour les fonctions suivantes

• définir les propriétés du message (destinataires, contenu ...)

• envoyer le message

• éventuellement, créer et envoyer d'autres messages

• fermer la session

Méthodes pour l'envoi d'email

NOUVELLE_SESSION_SMTP

NOUVELLE_SESSION_SIMPLE_MAPI

NOUVELLE_SESSION

NOUVEAU_MESSAGE

MESSAGE_SUJET

MESSAGE_TEXTE

MESSAGE_PARAMETRES

AJOUTER_ADRESSE

AJOUTER_ADRESSES

AJOUTER_FICHIER

VERIFIER_MESSAGE

ENVOYER_MESSAGE

EFFACER_MESSAGE

EFFACER_ADRESSES

EFFACER_FICHIERS

TEXTE_ERREUR

TERMINER_SESSION

ACTIVER_LOG

MUET

Exemple

Description des valeurs des erreurs

Méthode de transformation de texte (interprétation de formules) :

TRANSFORMER

Méthodes FTP / HTTP :

FTP_CONNECT

FTP_STATUS

FTP_CAPABILITIES

FTP_GET

FTP_PUT

FTP_DISCONNECT

Exemple FTP

HTTP_DOWNLOAD

La méthode NOUVELLE_SESSION_SMTP

Création d'une nouvelle session SMTP. L'authentification est nécessaire selon les serveurs.

Il est préférable d'utiliser la méthode NOUVELLE_SESSION pour profiter du paramétrage de l'utilisateur.

Paramètres :

Double Reference id_session ("ID de la session")

ID de la session

Chaine serveur ("Serveur SMTP")

Serveur smtp, obligatoire (ex: smtp.wanadoo.fr ou 200.169.52.126)

Entier port    ("Port SMTP")

Port smtp, facultatif (par défaut 25)

Chaine domaine_exp ("Domaine de l'expéditeur, facultatif")

Domaine ou nom de la machine émettrice, facultatif.

Certains serveur nécessitent cette donnée. Si le domaine est vide, il est rempli par le nom complet de l'ordinateur (ex: machine1.masociete.fr).

Entier securite    ("Type de sécurité TLS/SSL, facultatif")

Type de sécurité : 0=aucune, 1=STARTTSL, 2=SSL

Chaine code_utilisateur   ("Utilisateur")

Code utilisateur pour l'authentification.

Chaine motDePasse  ("Mot de passe")

Mot de passe pour l'authentification. Attention, si on récupère le mot de passe saisi via le paramétrage utilisateur, il est crypté. Faire précéder la chaine par "Crypte:".

La méthode NOUVELLE_SESSION_SIMPLE_MAPI

Création d'une nouvelle session Simple MAPI. Il est préférable d'utiliser la méthode NOUVELLE_SESSION pour profiter du paramétrage de l'utilisateur.

Paramètres :

Double Reference id_session ("ID de la session")

ID de la session

Chaine code_profil ("Nom du profil/compte")

nom du profil, facultatif et limité à 256 caractères.

Le profil n'est pas un compte (autre adresse e-mail) mais un ensemble de paramètres et/ou comptes dans votre messagerie : Voir "Courrier" dans le Panneau de configuration.

A part pour Exchange, généralement, il est inutile de préciser le profil.

Chaine motDePasse  ("Mot de passe du profil/compte")

Mot de passe du profil, facultatif

Double flags       ("Paramètres supplémentaires (flags MAPI)")

Flags (options) MAPI, facultatif. Consultez, sur MSDN, les fonctions MAPILogon et MAPISendMail.

Principales valeurs (additionner les valeurs pour utiliser plusieurs options) :

La méthode NOUVELLE_SESSION

Création d'une nouvelle session SMTP ou Simple MAPI selon le paramétrage défini au niveau de l'utilisateur en cours. Ce paramétrage est accessible dans Oxygène depuis la fiche de gestion de l'utilisateur.

Un message créé dans cette session reprendra automatiquement les autres paramètres comme l'adresse d'expéditeur (via AJOUTER_ADRESSE From ...) et les options (via MESSAGE_PARAMETRES). Remarque : les options seront modifiables contrairement à l'adresse de l'expéditeur.

Paramètres :

Double Reference id_session ("ID de la session")

ID de la session

Double flags       ("Paramètres supplémentaires (flags MAPI)")

Flags optionnels si session MAPI (cf. NOUVELLE_SESSION_SIMPLE_MAPI)

La méthode NOUVEAU_MESSAGE

Création d'un nouveau message.

Paramètres :

Double Reference id_message ("ID du message")

ID du message

Chaine sujet ("Objet du message",256)

Sujet (ou objet), facultatif et limité à 256 caractères

La méthode MESSAGE_SUJET

Définit ou modifie le sujet.

Paramètres :

Double id_message ("ID du message")

ID du message

Chaine sujet ("Objet du message",256)

Sujet (ou objet), facultatif et limité à 256 caractères

La méthode MESSAGE_TEXTE

Définit ou modifie le contenu du message et son format.

Si le format est de l'html, on recherche les références aux images et si ces dernières existent sur le disque dur, on les ajoute en tant que pièces jointes invisibles. Attention : les images avec des chemins relatifs ne peuvent être retrouvées que si 'texte' désigne un nom de fichier.

Quand on rédige un message en HTML, on peut ajouter son équivalent en texte brut pour les clients de messagerie ne supportant pas l'HTML (faire un deuxième appel à cette méthode).

Paramètres :

Double id_message ("ID du message")

ID du message

Chaine texte ("Contenu du message")

Contenu du message, facultatif. Si texte commence par "f:", la suite doit désigner un nom de fichier à lire.

Entier html  ("Le texte est en HTML [Vrai|Faux]")

Si html vaut true, texte est de l'HTML sinon c'est du texte brut (HTML uniquement pour SMTP)

La méthode MESSAGE_PARAMETRES

Définit les paramètres d'un message. Ces paramètres sont gérés uniquement par une session SMTP sauf pour la confirmation de lecture.

Paramètres :

Double id_message ("ID du message")

ID du message

Entier priorite_msg ("Priorité du message [1(très haute);5]")

priorité du message de 1(très haute) à 3(normale) et à 5 (très basse), facultatif

Entier accuseReception  ("Demande d'accusé de réception [Vrai|Faux]")

demande d'un accusé de réception (accusé de remise), facultatif (le serveur du destinataire a accepté le message)

Entier confirmationLecture ("Demande de confirmation de lecture [Vrai|Faux]")

demande d'une confirmation de lecture (message affiché sur l'écran du destinataire), facultatif.

Dans nos tests, cette option a fonctionné avec Outlook 2003 mais pas avec Outlook Express XP ni Thunderbird 1.7.

La méthode AJOUTER_ADRESSE

Définit l'adresse de l'expéditeur ou ajoute des destinataires. On ne peut pas définir d'expéditeur dans une session Simple MAPI puisqu'il est défini dans le profil.

Paramètres :

Double id_message ("ID du message")

ID du message

Chaine type       ("Type [From|To|CC|BCC]")

type expéditeur ou destinataire (From, To, CC ou BCC), obligatoire

Chaine adresse    ("Adresse email")

adresse valide (ex: dv@truc.fr), obligatoire

Chaine nom        ("Désignation")

nom complet (ex: David Vincent), facultatif. Attention, pour certains programmes MAPI (comme Outlook 2003), la saisie du nom est obligatoire.

La méthode AJOUTER_ADRESSES

Ajoute les adresses contenues dans une liste.

Paramètres :

Double id_message ("ID du message")

ID du message

Chaine type       ("Type [From|To|CC|BCC]")

type expéditeur ou destinataire ou vérification (From, To, CC, BCC ou vérification), obligatoire

Chaine adresses   ("Adresses email")

liste d'adresses, facultative.

Voici le format (guillemets facultatifs et désignation facultative) : "désignation" <nom@domaine.fr>. Les adresses doivent être séparée par des points virgules. Entre < et >, les espaces sont interdits.

Exemple : "Contact" <contact@memsoft.fr>; Sylvain Furlan<sfurlan@memsoft.fr> ; <support@memsoft.fr>

La méthode AJOUTER_FICHIER

Ajoute un fichier (ou pièce jointe). Si le fichier existe déjà (comparaison sur le chemin), le fichier n'est pas ajouté.

Paramètres :

Double id_message ("ID du message")

ID du message

Chaine chemin     ("Chemin d'accès complet")

chemin complet du fichier (ex: c:\documents\facture.pdf), obligatoire

La méthode VERIFIER_MESSAGE

Contrôle la validité d'un message, c'est à dire vérification de la présence : de l'adresse de l'expéditeur, d'au moins une adresse de destinataire, d'une adresse de serveur (si SMTP) et d'au moins une information (sujet, texte, contenu HTML (si SMTP) ou pièce jointe).

Paramètres :

Double id_session ("ID de la session")

ID de la session

Double id_message ("ID du message")

ID du message

La méthode ENVOYER_MESSAGE

Envoi réel du message.

Paramètres :

Double id_session ("ID de la session")

ID de la session

Double id_message ("ID du message")

ID du message

La méthode EFFACER_MESSAGE

Efface un message avec les adresses et les fichiers

Paramètres :

Double id_message ("ID du message")

ID du message

La méthode EFFACER_ADRESSES

Efface toutes les adresses du message.

Paramètres :

Double id_message ("ID du message")

ID du message

La méthode EFFACER_FICHIERS

Efface tous les fichiers (pièce jointes) du message.

Paramètres :

Double id_message ("ID du message")

ID du message

La méthode TEXTE_ERREUR

Traduit une valeur d'erreur en texte descriptif.

Paramètres :

Chaine Reference texte

Texte qui recevra la description de l'erreur.

Entier erreur

Valeur de l'erreur (ErreurRendue).

La méthode TERMINER_SESSION

Termine une session qu'elle soit SMTP ou Simple MAPI.

Paramètres :

Double id_session ("ID de la session")

ID de la session

La méthode ACTIVER_LOG

Active l'écriture dans oxydev\systeme\bin\sendmail.log de toute la communication avec le serveur SMTP.

Appelez cette méthode avant ENVOYER_MESSAGE.

Obsolète : il suffit de créer un fichier sendmail.log dans le répertoire oxydev\systeme\bin pour qu'il soit automatiquement rempli lors d'une connexion SMTP. Penser à supprimer ce fichier après vos tests.

Paramètres :

Entier activer ("Activer le log O/N")

Si 1, active le log.

La méthode MUET

Désactive l'affichage des BoiteMessage lors des erreurs. On peut toujours récupérer les codes erreurs avec ErreurRendue.

Paramètres :

Entier param ("Rendre muet 0/1")

Si 1, désactive les messages d'erreur..

Exemples

Voici un exemple simple envoyant un e-mail par SMTP avec une pièce jointe.

Voici un exemple simple utilisant les préférences définies au niveau de l'utilisateur Oxygène : 

Description des valeurs des erreurs

Voici la signification des valeurs retournées par les méthodes d'envoi d'e-mail.

Si une valeur n'est pas décrite ci dessous, elle correspond à une erreur des fonctions MAPI.

La méthode TRANSFORMER

Cette  méthode permet de personnaliser des fichiers en remplaçant des jetons par des données.

Cela fonctionne pour tout fichier ayant un codage ASCII comme les fichiers TXT, HTM, RTF, MHT, XML, CSV ... mais pas pour les fichiers codés en binaire comme les documents Microsoft Word, Excel, PDF, ...

Le principe est le remplacement de jetons par leur valeur dans du texte. Un jeton est une expression L4G entre une balise de début et une balise de fin : [# expression #]. L'expression L4G est interprétée donc elle peut être une variable ou un champ avec ou sans condition tout comme dans un état.

Ce traitement peut traiter plusieurs enregistrements de la table principale selon les filtres. Le chemin du fichier résultat doit être interprétable de façon à donner des noms distincts pour chaque enregistrement. Si aucun chemin n'est donné, la méthode reprend le nom du fichier d'entrée en insérant, avant l'extension, la valeur du premier champ.

On travaille sur une table principale mais on peut également gérer une autre table pour, par exemple, afficher les lignes d'un document. Cette table est dite de liste ou des lignes ; pour définir le début et la fin de la liste, il faut utiliser les jetons [#DEBUT_LISTE#] et [#FIN_LISTE#] (respecter la casse). Les champs de cette table sont accessibles par le contexte LISTE.

Fonctionnement :

• Lecture du fichier modèle et contrôles

• Filtre sur la table principale et calcul des variables locales ($DATE, $HEURE, $JOUR, $MOIS, $ANNEE, $LDATE)

• Pour chaque fiche de la table principale :

• • Lecture des interfaces des fiches en liens suivant les liens composants définis dans la table (pas de lecture des liens relationnels)

  • filtre et contrôle pour les lignes

  • Recherche séquentielle des jetons et interprétation

  • Sauvegarde dans un nouveau fichier

Exemples formats de documents codés en ASCII :

HTML :

+ peut être mis en corps d'email (SMTP)

- images enregistrées à l'extérieur du fichier

- conversion pas toujours idéale avec Word

RTF  :

+ images intégrées

- images converties en BMP d'où une taille décuplée

- ne pas être dans un corps d'email (sauf avec MAPI (Extended))

MHT  :

+ idem format HTML mais les images sont ajoutées à la fin du fichier

- lisible uniquement sur une plateforme Windows

- ne pas être dans un corps d'email

TXT  :

+ peut être en corps d'email

- pas de formatage de texte, pas d'images

Remarques :

On utilise les bornes [# et #] car elles sont inchangées lors de l'enregistrement sous Word en RTF et HTML (< est changé en &rt; en HTML).

On peut ainsi personnaliser un document créé avec Microsoft Word mais ce document doit être enregistré sous un format dit ASCII (HTML, RTF, MHT ou TXT) et non en tant que .doc car ce format est codé en binaire. De plus, l'enregistrement d'un RTF sous Word peut casser vos balises : formatez le document avec Word puis resauvegardez-le avec WordPad.

Paramètres :

Chaine p_fichier

Chemin et nom du fichier modèle

Chaine p_fichier_resultat

Chemin et nom du fichier à générer.

Peut être une chaîne à interpréter pour générer les noms de fichiers

Exemple : """c:\documents\piece"""+TABLE.NUMERO_DOC+""".rtf"""

Chaine p_base

Code de la base de données

Chaine p_table

Code de la table principale

Chaine p_filtre

Filtre sur la table principale.

Exemple : "DATE_CREATION {SuperieurA} ""31/12/2005"""

Pour obtenir un filtre, on peut appeler l'objet suivant :

AppelerObjet "$$"."$FLTR" (p_filtre, 1, p_base, p_table, "" )

Chaine p_monnaie

Identifiant de la monnaie principale

Date  p_monnaie_date

Date du cours de la monnaie

Double p_monnaie_cours

Valeur du cours de la monnaie

Chaine p_liste

Table des lignes

Chaine p_liste_filtre

Filtre sur la table des lignes. Les champs doivent être préfixés par le contexte LISTE.

Exemple : "LISTE.NUMERO {DebutePar} IDENT+""|"""

Pour obtenir un filtre, on peut appeler l'objet suivant :

AppelerObjet "$$"."$FLTR" (p_liste_filtre, 1, p_base, p_liste, "LISTE" )

Chaine p_liste_tri

Code du champ pour le classement. Le champ doit avoir un index séquentiel.

Pour obtenir un champ de classement, on peut appeler l'objet suivant :

AppelerObjet "$$"."$ORDR" (p_liste_tri,1, p_base, pliste,"")

ErreurRendue :

1 : Pas de fichier modèle valide

2 : Base <p_base> introuvable

3 : Table <p_table> introuvable dans la base <p_base>

4 : Table secondaire <p_liste> introuvable dans la base <p_base>

5 : Une balise de début existe sans balise de fin

On peut utiliser la méthode MUET pour afficher ou non les messages d'erreurs.

Fonctions FTP (à partir de la 8.11)

Des fonctions basiques de communication via le protocole FTP sont disponibles. On utilise la bibliothèque .net C# System.Net.FtpClient.

L'historique des commandes échangées avec le serveur FTP peut être sauvegardé dans un journal en créant le fichier oxydev\systeme\bin\ftp.log.

La méthode FTP_CONNECT

Connexion à un serveur avec nom d'utilisateur et mot de passe. Penser à se déconnecter avec la méthode FTP_DISCONNECT.

Parametres :

Chaine pServeur

Nom du serveur par adresse IP ou nom DNS.

Chaine pUtilisateur

Nom de l'utilisateur sur le serveur FTP

Chaine pMotDePasse

Mot de passe de pUtilisateur

La méthode FTP_STATUS

Récupère le texte du statut de la dernière action.

Parametres :

Chaine Reference pMsg

ErreurRendue :

0: non initialisé (FTP_CONNECT non fait)

1: non connecté (échec de connexion)

2: connecté

La méthode FTP_CAPABILITIES

Donne la liste des propriétés et des fonctions supportées par le serveur.

Parametres :

Chaine Reference pCapabilities

La méthode FTP_PUT

Envoi d'un fichier local sur le serveur FTP.

Parametres :

Chaine pFichierSrc

Chemin complet du fichier local.

Chaine pFichierDst

Chemin complet du fichier de destination.

La méthode FTP_GET

Téléchargement d'un fichier du serveur FTP sur un fichier local.

Parametres :

Chaine pFichierDst

Chemin complet du fichier distant.

Chaine pFichierSrc

Chemin complet du fichier local.

La méthode FTP_DISCONNECT

Déconnexion du serveur FTP.

Exemple FTP

Exemple simple d'envoi d'un fichier PDF local sur le serveur FTP :

AppliquerMethodeComposant SYSMAIL.FTP_CONNECT ("ftp.memsoft.fr", "Kevin", vFTPMotDePasse)
AppliquerMethodeComposant SYSMAIL.FTP_PUT ("C:\test\facture.pdf", "/fact/fact01.pdf")
Variables : Chaine msg
AppliquerMethodeComposant SYSMAIL.FTP_STATUS (msg)
Si ErreurRendue<>2 Alors
   BoiteMessage "put:"+ msg + SautDeLigne +"ErreurRendue:" + ErreurRendue
FinSi
AppliquerMethodeComposant SYSMAIL.FTP_DISCONNECT

La méthode HTTP_DOWNLOAD

Télécharge le contenu d'un fichier texte sur un serveur http. A n'utiliser que sur des petits fichiers, car il n'y a pas de jauge de progression ni moyen d'annuler le traitement.

Si le paramètre pDestination est vide, la méthode retourne le contenu du fichier dans celui-ci. Sinon mettre le chemin local du fichier dans lequel écrire le résultat.

NB : Le téléchargement se fait via l'ActiveX Msxml2.XMLHTTP.3.0. A partir de la 9.01.11.

Parametres :

Chaine pURL ("URL/Chemin http du fichier")

Chaine Reference pDestination ("Chemin du fichier de destination ou contenu")

Entier pTimeOut ("Délai max d'attente en secondes")

Entier pUTF8 ("Vrai=Ecrire le fichier en UTF8")