Version: 20 R6

POP3Transporter

La classe POP3Transporter vous permet de récupérer des messages à partir d'un serveur de messagerie POP3.

Objet POP3 Transporter

Les objets Transporter POP3 sont instanciés avec la commande POP3 New transporter. Leurs propriétés et fonctions sont les suivantes :


.acceptUnsecureConnection : Boolean True si 4D est autorisé à établir une connexion non chiffrée
.authenticationMode : Text le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie
.checkConnection() : Object vérifie la connexion en utilisant les informations stockées dans l'objet transporteur
.connectionTimeOut : Integer le temps d'attente maximum (en secondes) autorisé pour établir une connexion avec le serveur
.delete( msgNumber : Integer ) marque l'email msgNumber pour suppression sur le serveur POP3
.getBoxInfo() : Object retourne un objet `boxInfo` correspondant à la boite de réception désignée par l'objet POP3 transporter
.getMail( msgNumber : Integer { ; headerOnly : Boolean } ) : Object retourne l'objet `Email` correspondant au msgNumber dans la boite de réception désignée par l'objet POP3 transporter
.getMailInfo( msgNumber : Integer ) : Object
.getMailInfoList() : Collection retourne une collection d'objets `mailInfo` décrivant tous les messages dans la boite de réception désignée par le transporteur `POP3`
.getMIMEAsBlob( msgNumber : Integer ) : Blob renvoie un BLOB contenant le contenu MIME du message correspondant au msgNumber dans la boîte aux lettres désignée par l'objet `POP3_transporter`
.host : Text le nom ou l'adresse IP du serveur hôte
.logFile : Text le chemin du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie
.port : Integer le numéro de port utilisé pour les transactions de courrier
.undeleteAll() supprime tous les marqueurs de suppression définis sur les emails dans le `POP3_transporter`
.user : Text le nom d'utilisateur utilisé pour l'authentification sur le serveur de messagerie

POP3 New transporter

Historique

Release	Modifications
18 R2	Ajout

POP3 New transporter( server : Object ) : 4D.POP3Transporter

Paramètres	Type		Description
server	object	->	Informations sur le serveur IMAP
Résultat	4D.POP3Transporter	<-	Objet POP3 Transporter

Description

La commande POP3 New transporter configure une nouvelle connexion POP3en fonction du paramètre server et renvoie un nouvel objet POP3 transporter. L'objet transporteur retourné sera alors utilisé pour la réception d'emails.

Dans le paramètre server, passez un objet contenant les propriétés suivantes :

server	Valeur par défaut (si omise)
.acceptUnsecureConnection : Boolean True si 4D est autorisé à établir une connexion non chiffrée	False
.accessTokenOAuth2 : Text .accessTokenOAuth2 : Object Chaîne ou objet token représentant les informations d'autorisation OAuth2. Utilisé uniquement avec OAUTH2 `authenticationMode`. Si `accessTokenOAuth2` est utilisé mais que `authenticationMode` est omis, le protocole OAuth 2 est utilisé (si le serveur l'autorise). Non retourné dans l'objet SMTP transporter.	aucun
.authenticationMode : Text le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie	le mode d'authentification le plus sûr pris en charge par le serveur est utilisé
.connectionTimeOut : Integer le temps d'attente maximum (en secondes) autorisé pour établir une connexion avec le serveur	30
.host : Text le nom ou l'adresse IP du serveur hôte	obligatoire
.logFile : Text le chemin du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie	aucun
password : Text Mot de passe utilisateur pour l'authentification sur le serveur. Non retourné dans l'objet SMTP transporter.	aucun
.port : Integer le numéro de port utilisé pour les transactions de courrier	995
.user : Text le nom d'utilisateur utilisé pour l'authentification sur le serveur de messagerie	aucun

Résultat

La fonction renvoie un objet POP3 Transporter. Toutes les propriétés retournées sont en lecture seule.

La connexion POP3 est automatiquement fermée lorsque l'objet transporteur est détruit.

Exemple

 var $server : Object
 $server:=New object
 $server.host:="pop.gmail.com" //Obligatoire
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"
 $server.logFile:="LogTest.txt" //log à enregistrer dans le dossier Logs

 var $transporter : 4D.POP3Transporter
 $transporter:=POP3 New transporter($server)

 $status:=$transporter.checkConnection()
 If(Not($status.success))
    ALERT("An error occurred receiving the mail: "+$status.statusText)
 End if

4D.POP3Transporter.new()

4D.POP3Transporter.new( server : Object ) : 4D.POP3Transporter

Paramètres	Type		Description
server	Object	->	Informations sur le serveur IMAP
Résultat	4D.POP3Transporter	<-	Objet POP3 Transporter

Description

La fonction 4D.POP3Transporter.new() crée et retourne un nouvel objet de type 4D.POP3Transporter. Elle est identique à la commande POP3 New transporter (raccourci).

.acceptUnsecureConnection

Historique

Release	Modifications
17 R4	Ajout

.acceptUnsecureConnection : Boolean

Description

La propriété .acceptUnsecureConnection contient True si 4D est autorisé à établir une connexion non chiffrée lorsqu'une connexion chiffrée n'est pas possible.

Elle contient False si les connexions non chiffrées ne sont pas autorisées, auquel cas une erreur est retournée lorsque la connexion chiffrée n'est pas possible.

Ports sécurisés disponibles :

SMTP
- 465: SMTPS
- 587 ou 25 : SMTP avec mise à niveau STARTTLS si le serveur le prend en charge.
IMAP
- 143 : Port IMAP non chiffré
- 993 : IMAP avec mise à niveau STARTTLS si le serveur le prend en charge
POP3
- 110 : Port POP3 non chiffré
- 995 : POP3 avec mise à niveau STARTTLS si le serveur le prend en charge.

.authenticationMode

Historique

Release	Modifications
17 R4	Ajout

.authenticationMode : Text

Description

La propriété .authenticationMode contient le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie.

Par défaut, le mode le plus sécurisé pris en charge par le serveur est utilisé.

Valeurs possibles :

Valeur	Constantes	Commentaire
APOP	`POP3 authentication APOP`	Authentification à l'aide du protocole APOP (POP3 uniquement)
CRAM-MD5	`POP3 authentication CRAM MD5`	Authentification à l'aide du protocole CRAM-MD5
LOGIN	`POP3 authentication login`	Authentification à l'aide du protocole LOGIN
OAUTH2	`POP3 authentication OAUTH2`	Authentification à l'aide du protocole OAuth2
PLAIN	`POP3 authentication plain`	Authentification à l'aide du protocole PLAIN

.checkConnection()

Historique

Release	Modifications
17 R4	Ajout

.checkConnection() : Object

Paramètres	Type		Description
Résultat	Object	<-	Statut de la connexion de l'objet transporteur

Description

La fonction .checkConnection() vérifie la connexion en utilisant les informations stockées dans l'objet transporteur, recrée la connexion si nécessaire et renvoie le statut. Cette fonction vous permet de vérifier que les valeurs fournies par l'utilisateur sont valides et cohérentes.

Objet retourné

La fonction envoie une requête au serveur de mail et retourne un objet décrivant le statut. Cet objet peut avoir les propriétés suivantes :

Propriété		Type	Description
success		boolean	Vrai si la vérification a été effectuée avec succès, sinon Faux
status		number	(SMTP uniquement) Code du statut retourné par le serveur de messagerie (0 en cas de problème non lié au traitement du mail)
statusText		text	Message du statut retourné par le serveur de messagerie, ou dernière erreur retournée dans la pile d'erreurs 4D
errors		collection	Pile d'erreurs 4D (non retournée si une réponse du serveur de messagerie est reçue)
	[ ].errCode	number	Code d'erreur 4D
	[ ].message	text	Description de l'erreur 4D
	[ ].componentSignature	text	Signature du composant interne qui a retourné l'erreur

Exemple

 var $pw :  Text
 var $options : Object
 $options:=New object

 $pw:=Request("Please enter your password:")
 if(OK=1)
    $options.host:="pop3.gmail.com"

    $options.user:="test@gmail.com"
    $options.password:=$pw

    $transporter:=POP3 New transporter($options)

    $status:=$transporter.checkConnection()
    If($status.success)
       ALERT("POP3 connection check successful!")
    Else
       ALERT("Error: "+$status.statusText)
    End if
 End if

.connectionTimeOut

Historique

Release	Modifications
17 R5	Ajout

.connectionTimeOut : Integer

Description

La propriété .connectionTimeOut contient le temps d'attente maximum (en secondes) autorisé pour établir une connexion avec le serveur. Par défaut, si la propriété n'a pas été définie dans l'objet server (utilisé pour créer l'objet transporteur avec SMTP New transporter, POP3 New transporter, IMAP New transporter), la valeur utilisée est 30.

.delete()

Historique

Release	Modifications
18 R2	Ajout

.delete( msgNumber : Integer )

Paramètres	Type		Description
msgNumber	Integer	->	Numéro du message à supprimer

Description

La fonction .delete() marque l'email msgNumber pour suppression sur le serveur POP3.

Dans le paramètre msgNumber, passez le numéro de l'email à supprimer. Ce numéro est renvoyé dans la propriété number par la fonction .getMailInfoList().

L'exécution de cette méthode ne supprime pas réellement l'email. L'email marqué sera supprimé sur le serveur POP3 uniquement lorsque l'objet POP3_transporter (créé à l'aide de POP3 New transporter) sera détruit. Le marqueur pourra également être retiré via la fonction .undeleteAll().

Si la session courante se termine inopinément et que le connexion est fermée (ex : timeout, panne de réseau, etc.), un message d'erreur est généré et les messages marqués pour suppression demeureront sur le serveur POP3.

Exemple

 $mailInfoList:=$POP3_transporter.getMailInfoList()
 For each($mailInfo;$mailInfoList)
  // Marquer votre e-mail comme "à supprimer à la fin de la session"
    $POP3_transporter.delete($mailInfo.number)
 End for each
  // Forcer la fermeture de la session pour supprimer les e-mails marqués pour suppression
 CONFIRM("Selected messages will be deleted.";"Delete";"Undo")
 If(OK=1) //suppression confirmée
    $POP3_transporter:=Null
 Else
    $POP3_transporter.undeleteAll() //supprimer les marqueurs de suppression
 End if

.getBoxInfo()

Historique

Release	Modifications
18 R2	Ajout

.getBoxInfo() : Object

Paramètres	Type		Description
Résultat	Object	<-	Objet boxInfo

Description

La fonction .getBoxInfo() retourne un objet boxInfo correspondant à la boite de réception désignée par l'objet POP3 transporter. Cette fonction vous permet de récupérer des informations sur la boite de réception.

L'objet boxInfo contient les propriété suivantes :

Propriété	Type	Description
mailCount	Number	Nombre de messages contenus dans la boîte de réception
size	Number	Taille du message en octets

Exemple

 var $server; $boxinfo : Object

 $server:=New object
 $server.host:="pop.gmail.com" //Obligatoire
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=POP3 New transporter($server)

  //mailbox info
 $boxInfo:=$transporter.getBoxInfo()
 ALERT("The mailbox contains "+String($boxInfo.mailCount)+" messages.")

.getMail()

Historique

Release	Modifications
20	Prise en charge du paramètre headerOnly
18 R2	Ajout

.getMail( msgNumber : Integer { ; headerOnly : Boolean } ) : Object

Paramètres	Type		Description
msgNumber	Integer	->	Numéro du message dans la liste
headerOnly	Boolean	->	True pour télécharger uniquement les en-têtes de l'email (par défaut, False)
Résultat	Object	<-	Objet Email

Description

La fonction .getMail() retourne l'objet Email correspondant au msgNumber dans la boite de réception désignée par l'objet POP3 transporter. Cette fonction vous permet de gérer localement le contenu de l'email.

Passez dans msgNumber le numéro du message à récupérer. Ce numéro est renvoyé dans la propriété number par la fonction .getMailInfoList().

Optionnellement, vous pouvez passer true dans le paramètre headerOnly pour exclure les parties body de l'objet Email renvoyé. Seules les propriétés d'en-tête (headers, to, from...) sont ensuite renvoyées. Cette option vous permet d'optimiser l'étape de téléchargement lorsque beaucoup d'emails sont sur le serveur.

note

L'option headerOnly peut ne pas être prise en charge par le serveur.

La fonction retourne Null si :

msgNumber désigne un message inexistant,
le message a été marqué pour suppression à l'aide de .delete().

Objet retourné

.getMail() renvoie un objet Email.

Exemple

Vous souhaitez connaitre l'expéditeur du premier mail de la boite de réception :

 var $server; $transporter : Object
 var $mailInfo : Collection
 var $sender : Variant

 $server:=New object
 $server.host:="pop.gmail.com" //obligatoire
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=POP3 New transporter($server)

 $mailInfo:=$transporter.getMailInfoList()

 $sender:=$transporter.getMail($mailInfo[0].number).from

.getMailInfo()

Historique

Release	Modifications
18 R2	Ajout

.getMailInfo( msgNumber : Integer ) : Object

Paramètres	Type		Description
msgNumber	Integer	->	Numéro du message dans la liste
Résultat	Object	<-	Objet MailInfo

Description

La fonction .getMailInfo()retourne un objet mailInfo correspondant au msgNumber dans la boite de réception désignée par le transporteur POP3. Cette fonction vous permet de récupérer des informations sur l'email.

Dans le paramètre msgNumber, passez le numéro de l'email à récupérer. Ce numéro est renvoyé dans la propriété number par la fonction .getMailInfoList().

L'objet mailInfo retourné contient les propriété suivantes :

Propriété	Type	Description
size	Number	Taille du message en octets
id	Text	ID unique du message

La fonction retourne Null si :

msgNumber désigne un message inexistant,
le message a été marqué pour suppression à l'aide de .delete().

Exemple

 var $server; $mailInfo : Object
 var $mailNumber : Integer

 $server.host:="pop.gmail.com" //Mandatory
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 var $transporter : 4D.POP3Transporter
 $transporter:=POP3 New transporter($server)

  //message info
 $mailInfo:=$transporter.getMailInfo(1) //get the first mail
 If($mailInfo #Null)
    ALERT("First mail size is:"+String($mailInfo.size)+" bytes.")
 End if

.getMailInfoList()

Historique

Release	Modifications
18 R2	Ajout

.getMailInfoList() : Collection

Paramètres	Type		Description
Résultat	Collection	<-	Collection d'objets `mailInfo`

Description

La fonction .getMailInfoList() retourne une collection d'objets mailInfo décrivant tous les messages dans la boite de réception désignée par le transporteur POP3. Cette fonction vous permet de gérer localement les listes de messages situés sur le serveur de messagerie POP3.

Chaque objet mailInfo retourné contient les propriété suivantes :

Propriété	Type	Description
[ ].size	Number	Taille du message en octets
[ ].number	Number	Numéro du message
[ ].id	Text	ID unique du message (utile si vous stockez le message localement)

Si la boîte de réception ne contient pas de message, une collection vide est retournée.

Propriétés number et ID

number est le numéro d'un message de la boite de réception au moment de la création du POP3_transporter. La propriété number n'est pas une valeur statique liée à un message spécifique. Elle change d'une session à l'autre en fonction de sa relation à d'autres messages de la boîte de réception au moment de l'ouverture de la session. Les numéros attribués aux messages ne sont valables que pendant la durée de vie de l'objet POP3_transporter. Lorsque le POP3_transporter est supprimé, les messages marqués pour suppression seront supprimés. Lorsque l'utilisateur se reconnecte au serveur, les messages courants de la boîte de réception sont renumérotés de 1 à x.

A l'inverse, id est un numéro unique assigné à un message lorsqu'il a été reçu par le serveur. Ce numéro est calculé à l'aide de l'heure et de la date de réception du message et sa valeur est assignée par votre serveur POP3. Malheureusement, les serveurs POP3 n'utilisent pas l'id comme référence primaire à leurs messages. Durant les sessions POP3, vous aurez besoin d'indiquer le number comme référence aux messages du serveur. Les développeurs doivent être vigilants s'ils développent des solutions qui importent des références aux messages dans une base de données tout en laissant le corps du message sur le serveur.

Exemple

Vous souhaitez connaitre le nombre total d'emails de la boîte de réception ainsi que leur taille :

 var $server : Object
 $server:=New object
 $server.host:="pop.gmail.com" //Obligatoire
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 var $transporter : 4D.POP3Transporter
 $transporter:=POP3 New transporter($server)

 C_COLLECTION($mailInfo)
 C_LONGINT($vNum;$vSize)

 $mailInfo:=$transporter.getMailInfoList()
 $vNum:=$mailInfo.length
 $vSize:=$mailInfo.sum("size")

 ALERT("The mailbox contains "+String($vNum)+" message(s) for "+String($vSize)+" bytes.")

.getMIMEAsBlob()

Historique

Release	Modifications
18 R3	Ajout

.getMIMEAsBlob( msgNumber : Integer ) : Blob

Paramètres	Type		Description
msgNumber	Integer	->	Numéro du message dans la liste
Résultat	Blob	<-	Blob de la chaine MIME retournée par le serveur mail

Description

La fonction .getMIMEAsBlob() renvoie un BLOB contenant le contenu MIME du message correspondant au msgNumber dans la boîte aux lettres désignée par l'objet POP3_transporter.

Dans le paramètre msgNumber, passez le numéro de l'email à récupérer. Ce numéro est renvoyé dans la propriété number par la fonction .getMailInfoList().

La fonction retourne un Blob vide si :

msgNumber désigne un message inexistant,
le message a été marqué pour suppression à l'aide de .delete().

BLOB retourné

.getMIMEAsBlob() renvoie un BLOB qui peut être archivé dans une base de données ou converti en un objet Email avec la commande MAIL Convert from MIME.

Exemple

Vous souhaitez connaitre le nombre total d'emails de la boîte de réception ainsi que leur taille :

 var $server : Object
 var $mailInfo : Collection
 var $blob : Blob
 var $transporter : 4D.POP3Transporter

 $server:=New object
 $server.host:="pop.gmail.com"
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=POP3 New transporter($server)

 $mailInfo:=$transporter.getMailInfoList()
 $blob:=$transporter.getMIMEAsBlob($mailInfo[0].number)

.host

Historique

Release	Modifications
17 R5	Ajout

.host : Text

Description

La propriété .host contient le nom ou l'adresse IP du serveur hôte. Utilisée pour les échanges de courrier (SMTP, POP3, IMAP).

.logFile

Historique

Release	Modifications
17 R5	Ajout

.logFile : Text

Description

La propriété .logFile contient le chemin du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie. Le chemin peut être relatif (au dossier Logs courant) ou absolu.

Contrairement aux fichiers log habituels (activés via la commande SET DATABASE PARAMETER), les fichiers log étendus stockent le contenu MIME de tous les emails envoyés et n'ont pas de limite de taille. Pour plus d'informations sur les fichiers log étendus, reportez-vous à :

Connexions SMTP - 4DSMTPLog.txt
Connexions POP3 - 4DPOP3Log.txt
Connexions IMAP - 4DIMAPLog.txt

.port

Historique

Release	Modifications
17 R4	Ajout

.port : Integer

Description

La propriété .port contient le numéro de port utilisé pour les transactions de courrier. Par défaut, si la propriété port n'a pas été définie dans l'objet server (utilisé pour créer l'objet transporteur avec SMTP New transporter, POP3 New transporter, IMAP New transporter), le port utilisé est :

SMTP - 587
POP3 - 995
IMAP - 993

.undeleteAll()

Historique

Release	Modifications
18 R2	Ajout

.undeleteAll()

Paramètres	Type		Description
			Ne requiert aucun paramètre

Description

La fonction .undeleteAll() supprime tous les marqueurs de suppression définis sur les emails dans le POP3_transporter.

.user

Historique

Release	Modifications
17 R4	Ajout

.user : Text

Description

La propriété .user contient le nom d'utilisateur utilisé pour l'authentification sur le serveur de messagerie.

Objet POP3 Transporter​

POP3 New transporter​

Description​

Résultat​

Exemple​

4D.POP3Transporter.new()​

Description​

.acceptUnsecureConnection​

Description​

.authenticationMode​

Description​

.checkConnection()​

Description​

Objet retourné​

Exemple​

.connectionTimeOut​

Description​

.delete()​

Description​

Exemple​

.getBoxInfo()​

Description​

Exemple​

.getMail()​

Description​

Exemple​

.getMailInfo()​

Description​

Exemple​

.getMailInfoList()​

Description​

Propriétés number et ID​

Exemple​

.getMIMEAsBlob()​

Description​

Exemple​

.host​

Description​

.logFile​

Description​

.port​

Description​

.undeleteAll()​

Description​

.user​

Description​

Objet POP3 Transporter

POP3 New transporter

Description

Résultat

Exemple

4D.POP3Transporter.new()

Description

.acceptUnsecureConnection

Description

.authenticationMode

Description

.checkConnection()

Description

Objet retourné

Exemple

.connectionTimeOut

Description

.delete()

Description

Exemple

.getBoxInfo()

Description

Exemple

.getMail()

Description

Exemple

.getMailInfo()

Description

Exemple

.getMailInfoList()

Description

Propriétés number et ID

Exemple

.getMIMEAsBlob()

Description

Exemple

.host

Description

.logFile

Description

.port

Description

.undeleteAll()

Description

.user

Description