Version: 20 R5 BETA

POP3Transporter

The POP3Transporter class allows you to retrieve messages from a POP3 email server.

Objet POP3 Transporter

POP3 Transporter objects are instantiated with the POP3 New transporter command. Leurs propriétés et fonctions sont les suivantes :


.acceptUnsecureConnection : Boolean    True if 4D is allowed to establish an unencrypted connection
.authenticationMode : Text    the authentication mode used to open the session on the mail server
.checkConnection() : Object     checks the connection using information stored in the transporter object
.connectionTimeOut : Integer    the maximum wait time (in seconds) allowed to establish a connection to the server
.delete( msgNumber : Integer )    flags the msgNumber email for deletion from the POP3 server
.getBoxInfo() : Object    returns a `boxInfo` object corresponding to the mailbox designated by the `POP3 transporter`
.getMail( msgNumber : Integer { ; headerOnly : Boolean } ) : Object    returns the `Email` object corresponding to the msgNumber in the mailbox designated by the `POP3 transporter`
.getMailInfo( msgNumber : Integer ) : Object    returns a `mailInfo` object corresponding corresponding to the msgNumber in the mailbox designated by the `POP3 transporter`
.getMailInfoList() : Collection    returns a collection of `mailInfo` objects describing all messages in the mailbox designated by the `POP3 transporter`
.getMIMEAsBlob( msgNumber : Integer ) : Blob    returns a BLOB containing the MIME contents for the message corresponding to the msgNumber in the mailbox designated by the `POP3_transporter`
.host : Text    the name or the IP address of the host server
.logFile : Text    the path of the extended log file defined (if any) for the mail connection
.port : Integer     the port number used for mail transactions
.undeleteAll()    removes all delete flags set on the emails in the `POP3_transporter`
.user : Text     the user name used for authentication on the mail server

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	<-	POP3 transporter object

Description

The POP3 New transporter command configures a new POP3 connectionaccording to the server parameter and returns a new POP3 transporter object. L'objet transporteur retourné sera alors utilisé pour la réception d'emails.

In the server parameter, pass an object containing the following properties:

server	Valeur par défaut (si omise)
.acceptUnsecureConnection : Boolean    True if 4D is allowed to establish an unencrypted connection	False
.accessTokenOAuth2: Text .accessTokenOAuth2: Object Text string or token object representing OAuth2 authorization credentials. Used only with OAUTH2 `authenticationMode`. If `accessTokenOAuth2` is used but `authenticationMode` is omitted, the OAuth 2 protocol is used (if allowed by the server). Not returned in SMTP transporter object.	aucun
.authenticationMode : Text    the authentication mode used to open the session on the mail server	le mode d'authentification le plus sûr pris en charge par le serveur est utilisé
.connectionTimeOut : Integer    the maximum wait time (in seconds) allowed to establish a connection to the server	30
.host : Text    the name or the IP address of the host server	obligatoire
.logFile : Text    the path of the extended log file defined (if any) for the mail connection	aucun
.password : Text User password for authentication on the server. Not returned in SMTP transporter object.	aucun
.port : Integer     the port number used for mail transactions	995
.user : Text     the user name used for authentication on the mail server	aucun

Résultat

The function returns a POP3 transporter object. All returned properties are read-only.

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	<-	POP3 transporter object

Description

The 4D.POP3Transporter.new() function creates and returns a new object of the 4D.POP3Transporter type. It is identical to the POP3 New transporter command (shortcut).

.acceptUnsecureConnection

Historique

Release	Modifications
17 R4	Ajout

.acceptUnsecureConnection : Boolean

Description

The .acceptUnsecureConnection property contains True if 4D is allowed to establish an unencrypted connection when encrypted connection is not possible.

It contains False if unencrypted connections are unallowed, in which case an error in returned when encrypted connection is not 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

The .authenticationMode property contains the authentication mode used to open the session on the mail server.

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

The .checkConnection() function checks the connection using information stored in the transporter object, recreates the connection if necessary, and returns the status. 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

The .connectionTimeOut property contains the maximum wait time (in seconds) allowed to establish a connection to the server. By default, if the property has not been set in the server object (used to create the transporter object with SMTP New transporter, POP3 New transporter, or IMAP New transporter), the value is 30.

.delete()

Historique

Release	Modifications
18 R2	Ajout

.delete( msgNumber : Integer )

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

Description

The .delete( ) function flags the msgNumber email for deletion from the POP3 server.

In the msgNumber parameter, pass the number of the email to delete. This number is returned in the number property by the .getMailInfoList() method.

L'exécution de cette méthode ne supprime pas réellement l'email. The flagged email will be deleted from the POP3 server only when the POP3_transporter object (created with POP3 New transporter) is destroyed. The flag could be also be removed using the .undeleteAll() method.

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

The .getBoxInfo() function returns a boxInfo object corresponding to the mailbox designated by the POP3 transporter. Cette fonction vous permet de récupérer des informations sur la boite de réception.

The boxInfo object returned contains the following properties:

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	Support of headerOnly parameter
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	<-	Email object

Description

The .getMail() function returns the Email object corresponding to the msgNumber in the mailbox designated by the POP3 transporter. Cette fonction vous permet de gérer localement le contenu de l'email.

Pass in msgNumber the number of the message to retrieve. This number is returned in the number property by the .getMailInfoList() function.

Optionally, you can pass true in the headerOnly parameter to exclude the body parts from the returned Email object. Only headers properties (headers, to, from...) are then returned. Cette option vous permet d'optimiser l'étape de téléchargement lorsque beaucoup d'emails sont sur le serveur.

note

The headerOnly option may not be supported by the server.

La fonction retourne Null si :

msgNumber designates a non-existing message,
the message was marked for deletion using .delete().

Returned object

.getMail() returns an Email object.

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

The .getMailInfo() function returns a mailInfo object corresponding corresponding to the msgNumber in the mailbox designated by the POP3 transporter. Cette fonction vous permet de récupérer des informations sur l'email.

In msgNumber, pass the number of the message to retrieve. This number is returned in the number property by the .getMailInfoList() method.

The mailInfo object returned contains the following properties:

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

The method returns Null if:

msgNumber designates a non-existing message,
the message was marked for deletion using .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 of `mailInfo` objects

Description

The .getMailInfoList() function returns a collection of mailInfo objects describing all messages in the mailbox designated by the POP3 transporter. Cette fonction vous permet de gérer localement les listes de messages situés sur le serveur de messagerie POP3.

Each mailInfo object in the returned collection contains the following properties:

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 is the number of a message in the mailbox at the time the POP3_transporter was created. The number property is not a static value in relation to any specific message and will change from session to session dependent on its relation to other messages in the mailbox at the time the session was opened. The numbers assigned to the messages are only valid during the lifetime of the POP3_transporter. At the time the POP3_transporter is deleted any message marked for deletion will be removed. Lorsque l'utilisateur se reconnecte au serveur, les messages courants de la boîte de réception sont renumérotés de 1 à x.

The id however is a unique number assigned to the message when it was received by the server. 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. Unfortunately, POP3 servers do not use the id as the primary reference to their messages. Throughout the POP3 sessions you will need to specify the number as the reference to messages on the server. 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

The .getMIMEAsBlob() function returns a BLOB containing the MIME contents for the message corresponding to the msgNumber in the mailbox designated by the POP3_transporter.

In msgNumber, pass the number of the message to retrieve. This number is returned in the number property by the .getMailInfoList() method.

La fonction retourne un Blob vide si :

msgNumber designates a non-existing message,
the message was marked for deletion using .delete().

BLOB retourné

.getMIMEAsBlob() returns a BLOB which can be archived in a database or converted to an Email object with the MAIL Convert from MIME command.

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

The .host property contains the name or the IP address of the host server. Utilisée pour les échanges de courrier (SMTP, POP3, IMAP).

.logFile

Historique

Release	Modifications
17 R5	Ajout

.logFile : Text

Description

The .logFile property contains the path of the extended log file defined (if any) for the mail connection. Le chemin peut être relatif (au dossier Logs courant) ou absolu.

Unlike regular log files (enabled via the SET DATABASE PARAMETER command), extended log files store MIME contents of all sent mails and do not have any size limit. Pour plus d'informations sur les fichiers log étendus, reportez-vous à :

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

.port

Historique

Release	Modifications
17 R4	Ajout

.port : Integer

Description

The .port property contains the port number used for mail transactions. By default, if the port property has not been set in the server object (used to create the transporter object with SMTP New transporter, POP3 New transporter, IMAP New transporter), the port used is:

SMTP - 587
POP3 - 995
IMAP - 993

.undeleteAll()

Historique

Release	Modifications
18 R2	Ajout

.undeleteAll()

Paramètres	Type		Description
			Ne requiert aucun paramètre

Description

The .undeleteAll() function removes all delete flags set on the emails in the POP3_transporter.

.user

Historique

Release	Modifications
17 R4	Ajout

.user : Text

Description

The .user property contains the user name used for authentication on the mail server.

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