Edit

POP3Transporter

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

POP3 Transporter object

POP3 Transporter objects are instantiated with the POP3 New transporter command. They provide the following properties and functions:

.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 )     marca o email msgNumber para ser apagado do servidor POP3
.getBoxInfo() : Object     retorna um objeto boxInfo correspondente ao mailbox determinado pelo POP3 transporter
.getMail( msgNumber : Integer ) : Object     retorna o objetoEmail correspondente a msgNumber na mailbox determinada pelo POP3 transporter
.getMailInfo( msgNumber : Integer ) : Object
.getMailInfoList() : Collection     retorna uma coleção de objetos mailInfo descrevendo todas as mensagens na mailbox determinada para o POP3 transporter
.getMIMEAsBlob( msgNumber : Integer ) : Blob     retorna uma BLOB contendo os conteúdos MIME para a mensagem correspondente a msgNumber na mailbox determinada pelo 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()     remove todas as marcações para apagar nos emails no POP3_transporter
.user : Text      the user name used for authentication on the mail server

POP3 New transporter

Histórico

Versão	Mudanças
v18 R2	Adicionado

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

Parameter	Type		Descrição
server	object	->	Mail server information
Resultado	4D.POP3Transporter	<-	Objeto POP3 transporter

Descrição

O comando POP3 New transporter configura uma nova conexão POP3de acordo com o parâmetro server e retorna um novo objetoPOP3 transporter. The returned transporter object will then usually be used to receive emails.

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

server	Default value (if omitted)
.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.	nenhum
.authenticationMode : Text     the authentication mode used to open the session on the mail server	the most secure authentication mode supported by the server is used
.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	mandatory
.logFile : Text     the path of the extended log file defined (if any) for the mail connection	nenhum
.password : Text User password for authentication on the server. Not returned in SMTP transporter object.	nenhum
.port : Integer      the port number used for mail transactions	995
.user : Text      the user name used for authentication on the mail server	nenhum

Resultado

A função retorna um objeto POP3 transporter. All returned properties are read-only.

The POP3 connection is automatically closed when the transporter object is destroyed.

Exemplo

 var $server : Object
 $server:=New object
 $server.host:="pop.gmail.com" //Mandatory
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"
 $server.logFile:="LogTest.txt" //log to save in the Logs folder

 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

Parameter	Type		Descrição
server	Objeto	->	Mail server information
Resultado	4D.POP3Transporter	<-	Objeto POP3 transporter

Descrição

A função 4D.POP3Transporter.new() cria e retorna um novo objeto do tipo 4D.POP3Transporter. Isso é idêntico ao comando (atalho) POP3 New transporter.

.acceptUnsecureConnection

Histórico

Versão	Mudanças
v17 R4	Adicionado

.acceptUnsecureConnection : Boolean

Descrição

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.

Available secured ports are:

• SMTP

  • 465: SMTPS
  • 587 or 25: SMTP with STARTTLS upgrade if supported by the server.

• IMAP

  • 143: IMAP non-encrypted port
  • 993: IMAP with STARTTLS upgrade if supported by the server

• POP3

  • 110: POP3 non-encrypted port
  • 995: POP3 with STARTTLS upgrade if supported by the server.

.authenticationMode

Histórico

Versão	Mudanças
v17 R4	Adicionado

.authenticationMode : Text

Descrição

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

By default, the most secured mode supported by the server is used.

Possible values are:

Value	Constantes	Comment
APOP	POP3 authentication APOP	Authentication using APOP protocol (POP3 only)
CRAM-MD5	POP3 authentication CRAM-MD5	Authentication using CRAM-MD5 protocol
LOGIN	POP3 authentication login	Authentication using LOGIN protocol
OAUTH2	POP3 authentication OAUTH2	Authentication using OAuth2 protocol
PLAIN	POP3 authentication plain	Authentication using PLAIN protocol

.checkConnection()

Histórico

Versão	Mudanças
v17 R4	Adicionado

.checkConnection() : Object

Parameter	Type		Descrição
Resultado	Objeto	<-	Status of the transporter object connection

Descrição

The .checkConnection() function checks the connection using information stored in the transporter object, recreates the connection if necessary, and returns the status. This function allows you to verify that the values provided by the user are valid and consistent.

Returned object

The function sends a request to the mail server and returns an object describing the mail status. This object can contain the following properties:

Propriedade		Type	Descrição
success		booleano	True if the check is successful, False otherwise
status		number	(SMTP only) Status code returned by the mail server (0 in case of an issue unrelated to the mail processing)
statusText		texto	Status message returned by the mail server, or last error returned in the 4D error stack
errors		collection	4D error stack (not returned if a mail server response is received)
	[ ].errCode	number	4D error code
	[ ].message	texto	Description of the 4D error
	[ ].componentSignature	texto	Signature of the internal component which returned the error

Exemplo

 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

Histórico

Versão	Mudanças
v17 R5	Adicionado

.connectionTimeOut : Integer

Descrição

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()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.delete( msgNumber : Integer )

Parameter	Type		Descrição
msgNumber	Integer	->	Número da mensagem que vai ser apagada

Descrição

A função .delete( ) function marca o email msgNumber para ser apagado do servidor POP3.

No parâmetro msgNumber, passe o número do email a apagar. O número é retornado na propriedade número pelo método .getMailInfoList().

Executar esse método não remove de verdade qualquer email. O email marcado será apagado do servidor POP3 apenas quando o objetoPOP3_transporter (criado com POP3 New transporter) for destruído. A marcação pode ser removida com o método .undeleteAll().

If the current session unexpectedly terminates and the connection is closed (e.g., timeout, network failure, etc.), an error message is generated and messages marked for deletion will remain on the POP3 server.

Exemplo

 $mailInfoList:=$POP3_transporter.getMailInfoList()
 For each($mailInfo;$mailInfoList)
  // Mark your mail as "to be deleted at the end of the session"
    $POP3_transporter.delete($mailInfo.number)
 End for each
  // Force the session closure to delete the mails marked for deletion
 CONFIRM("Selected messages will be deleted.";"Delete";"Undo")
 If(OK=1) //deletion confirmed
    $POP3_transporter:=Null
 Else
    $POP3_transporter.undeleteAll() //remove deletion flags
 End if

.getBoxInfo()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.getBoxInfo() : Object

Parameter	Type		Descrição
Resultado	Objeto	<-	boxInfo object

Descrição

A função .getBoxInfo() retorna um objeto boxInfo correspondente ao mailbox determinado pelo POP3 transporter. Essa função permite que recupere informação sobre o mailbox.

O objeto boxInfo retornado contém as funcionalidades abaixo:

Propriedade	Type	Descrição
mailCount	Número	Number of messages in the mailbox
size	Número	Tamanho da mensagem em bytes

Exemplo

 var $server; $boxinfo : Object

 $server:=New object
 $server.host:="pop.gmail.com" //Mandatory
 $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()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.getMail( msgNumber : Integer ) : Object

Parameter	Type		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultado	Objeto	<-	Email object

Descrição

A função .getMail() retorna o objetoEmail correspondente a msgNumber na mailbox determinada pelo POP3 transporter. Essa função permite manejar localmente os conteúdos de email.

Passe em msgNumber o número da mensagem a recuperar. O número é retornado na propriedade número pela função .getMailInfoList().

O método retorna Null se:

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

Returned object

.getMail() returns an Email object.

Exemplo

Se quiser saber o emissário do primeiro email da mailbox:

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

 $server:=New object
 $server.host:="pop.gmail.com" //Mandatory
 $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()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.getMailInfo( msgNumber : Integer ) : Object

Parameter	Type		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultado	Objeto	<-	mailInfo object

Descrição

A função .getMail()retorna o objetomailInfo correspondente a msgNumber na mailbox determinada pelo POP3 transporter. Essa função permite que recupere informação sobre o email.

Passe em msgNumber o número da mensagem a recuperar. O número é retornado na propriedade número pelo método .getMailInfoList().

O objeto mailInfo retornado contém as funcionalidades abaixo:

Propriedade	Type	Descrição
size	Número	Tamanho da mensagem em bytes
id	Texto	ID única da mensagem

O método retorna Null se:

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

Exemplo

 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()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.getMailInfoList() : Collection

Parameter	Type		Descrição
Resultado	Coleção	<-	Collection of mailInfo objects

Descrição

A função.getMailInfoList() retorna uma coleção de objetos mailInfo descrevendo todas as mensagens na mailbox determinada para o POP3 transporter. Essa função permite gerenciar localmente a lista de mensagens localizadas no servidor POP3.

Cada objeto mailInfo na coleção retornada contém as propriedades abaixo:

Propriedade	Type	Descrição
[ ].size	Número	Tamanho da mensagem em bytes
[ ].number	Número	Número da mensagem
[ ].id	Texto	ID único da mensagem (útil se armazenar a mensagem localmente)

Se a mailbox não conter uma mensagem, uma coleção vazia é retornada.

número e propriedades ID

number é o número de uma mensagem no mailbox no momento em que POP3_transporter for criado. A propriedade number não é um valor estático em relação a qualquer mensagem específica e vai mudar de sessão a sessão dependendo de sua relação com outras mensagens no mailibox na hora em que a sessão for aberta. Os números atribuídos às mensagens só são válidos durante a duração do POP3_transporter. No momento em que POP3_transporter for apagado qualquer mensagem marcada para ser apagada será removida. Quando o usuário se registrar de volta no servidor, as mensagens atuais no mailbox serão numeradas de 1 a x.

Entretanto, id é um número único atribuído à mensagem quando for recebida pelo servidor. Esse número é calculado usando a hora e data que a mensagem for recebida e é um valor atribuído ao seu servidor POP3. Infelizmente, servidores POP3 não usam a referência primária id para suas mensagens. Através das sessões POP3 precisa especificar o number como a referência às mensagens no servidor. Desenvolvedores podem precisar ter cuirdado se desenvolverem soluções que trazem referências às mensagens na database mas deixam o corpo da mensagem no servidor.

Exemplo

Se quiser saber o número total e tamanho dos emails nas mailbox:

 var $server : Object
 $server:=New object
 $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)

 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()

Histórico

Versão	Mudanças
v18 R3	Adicionado

.getMIMEAsBlob( msgNumber : Integer ) : Blob

Parameter	Type		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultado	Blob	<-	Blob da string MIME retornado do servidor mail

Descrição

A função .getMIMEAsBlob() retorna uma BLOB contendo os conteúdos MIME para a mensagem correspondente a msgNumber na mailbox determinada pelo POP3_transporter.

Passe em msgNumber o número da mensagem a recuperar. O número é retornado na propriedade número pelo método .getMailInfoList().

O método retorna uma BLOB vazia se:

• msgNumber designates a non-existing message,
• a mensagem foi marcada para apagar usando .delete().

BLOB devolvido

.getMIMEAsBlob() retorna um BLOB que pode ser arquivado em um banco de dados ou convertido a um objeto Email com o comando MAIL Convert from MIME.

Exemplo

Se quiser saber o número total e tamanho dos emails nas mailbox:

 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

Histórico

Versão	Mudanças
v17 R5	Adicionado

.host : Text

Descrição

The .host property contains the name or the IP address of the host server. Used for mail transactions (SMTP, POP3, IMAP).

.logFile

Histórico

Versão	Mudanças
v17 R5	Adicionado

.logFile : Text

Descrição

The .logFile property contains the path of the extended log file defined (if any) for the mail connection. It can be relative (to the current Logs folder) or absolute.

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. For more information about extended log files, refer to:

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

.port

Histórico

Versão	Mudanças
v17 R4	Adicionado

.port : Integer

Descrição

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()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.undeleteAll() | Parameter | Type | | Descrição | | --------- | ---- |::| ------------------------------- | | | | | Does not require any parameters |

Descrição

A função .undeleteAll() remove todas as marcações para apagar nos emails no POP3_transporter.

.user

Histórico

Versão	Mudanças
v17 R4	Adicionado

.user : Text

Descrição

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