Edit

POP3Transporter

O POP3Transporter permite recuperar mensagens de um servidor de email POP3.

Objeto POP3 transporter

Os objetos POP3 Transporter são instanciados com o comando POP3 New transporter. Eles oferecem as propriedades abaixo e funções:

.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

Parâmetros	Tipo		Descrição
server	objeto	->	Informação de servidor de correio
Resultados	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. O objeto transporter retornado vai geralmente ser usado para receber emails.

No parâmetro server, passe um objeto contendo as propriedades abaixo:

server	Valor padrão (se omitido)
.acceptUnsecureConnection : Boolean     True if 4D is allowed to establish an unencrypted connection	False
.accessTokenOAuth2: Text String texto representando OAuth2 credenciais de autorização. Só é usado com OAUTH2 authenticationMode. Se accessTokenOAuth2 for usado mas authenticationMode for omitido, o protocolo OAuth 2 é usado (se permitido pelo servidor). Não retornado em objetoSMTP transporter.	nenhum
.authenticationMode : Text     the authentication mode used to open the session on the mail server	o modo de autenticação mais seguro disponível no servidor é usado
.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	obrigatório
.logFile : Text     the path of the extended log file defined (if any) for the mail connection	nenhum
.password : Text A senha de usuário para autenticação no servidor. Não retornado em objetoSMTP transporter.	nenhum
.port : Integer      the port number used for mail transactions	995
.user : Text      the user name used for authentication on the mail server	nenhum

Resultados

A função retorna um objeto POP3 transporter. Todas as propriedades retornadas sãoapenas leitura.

A conexão POP3 é fechada automaticamente quando o objeto transportador for destruído.

Exemplo

 var $server : Object
 $server:=New object
 $server.host:="pop.gmail.com" //Obrigatório
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"
 $server.logFile:="LogTest.txt" //histórico para salvar na pasta 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

Parâmetros	Tipo		Descrição
server	Objeto	->	Informação de servidor de correio
Resultados	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

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.

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

Description

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	Constants	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		Description
Result	Objeto	<-	Status of the transporter object connection

Description

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:

Property		Type	Description
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		text	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	text	Description of the 4D error
	[ ].componentSignature	text	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

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

Histórico

Versão	Mudanças
v18 R2	Adicionado

.delete( msgNumber : Integer )

Parâmetros	Tipo		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().

Se a sessão atual terminar de forma inesperada e perder a conexão (por exemplo timeout, falha de rede, etc), uma mensagem de erro é gerada e mensagens marcadas para serem apagadas continuam no servidor POP3.

Exemplo

 $mailInfoList:=$POP3_transporter.getMailInfoList()
 For each($mailInfo;$mailInfoList)
  // Marca seu email a "to be deleted at the end of the session"
    $POP3_transporter.delete($mailInfo.number)
 End for each
  // Força que o fechamento da sessão apague os emails marcados para serem eliminados
 CONFIRM("Selected messages will be deleted.";"Delete";"Undo")
 If(OK=1) //eliminação confirmada
    $POP3_transporter:=Null
 Else
    $POP3_transporter.undeleteAll() //remove marcas de eliiminação
 End if

.getBoxInfo()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.getBoxInfo() : Object

Parâmetros	Tipo		Descrição
Resultados	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	Tipo	Descrição
mailCount	Número	Número de mensagens na caixa de email
size	Número	Tamanho da mensagem em bytes

Exemplo

 var $server; $boxinfo : Object

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

 $transporter:=POP3 New transporter($server)

  //mailbox informação
 $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

Parâmetros	Tipo		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultados	Objeto	<-	Objeto Email

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 determina uma mensagem não existente,
• a mensagem foi marcada para apagar usando .delete( ).

Objeto retornado

.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" //Obrigatório
 $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

Parâmetros	Tipo		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultados	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	Tipo	Descrição
size	Número	Tamanho da mensagem em bytes
id	Texto	ID única da mensagem

O método retorna Null se:

• msgNumber determina uma mensagem não existente,
• a mensagem foi marcada para apagar usando .delete( ).

Exemplo

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

 $server.host:="pop.gmail.com" //Obrigatório
 $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) //obtém o primeiro email
 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

Parâmetros	Tipo		Descrição
Resultados	Collection	<-	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	Tipo	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" //Obrigatório
 $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

Parâmetros	Tipo		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultados	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 determina uma mensagem não existente,
• 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

Description

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

Description

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

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

Histórico

Versão	Mudanças
v18 R2	Adicionado

.undeleteAll() | Parâmetros | Tipo | | Descrição | | ---------- | ---- |::| -------------------------- | | | | | Não exige nenhum parâmetro |

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

Description

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