Versão: 20 R6

POP3Transporter

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

Objeto POP3 transporter

POP3 Transporter objects are instantiated with the POP3 New transporter command. 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 ) 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`
.port : Integer the port number used for mail transactions

POP3 New transporter

História

Release	Mudanças
18 R2	Adicionado

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

Parâmetro	Tipo		Descrição
server	object	->	Informação de servidor de correio
Resultados	4D.POP3Transporter	<-	Objeto POP3 Transporter

Descrição

The POP3 New transporter command configures a new POP3 connectionaccording to the server parameter and returns a new POP3 transporter object. 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 .accessTokenOAuth2: Objeto Cadeia ou objeto token que representa as credenciais de autorização OAuth2. Usado somente com OAUTH2 `authenticationMode`. Se `accessTokenOAuth2` for usado, mas `authenticationMode` for omitido, o protocolo OAuth 2 será usado (se permitido pelo servidor). Não retornado no objeto SMTP 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	mandatory
.logFile : Text the path of the extended log file defined (if any) for the mail connection	nenhum
.password : Text Senha do usuário para autenticação no servidor. Não retornado no objeto SMTP transporter.	nenhum
.port : Integer the port number used for mail transactions	995
.port : Integer the port number used for mail transactions	nenhum

Resultados

A função retorna um objeto POP3 transporter. Todas as propriedades retornadas são apenas 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âmetro	Tipo		Descrição
server	Object	->	Informação de servidor de correio
Resultados	4D.POP3Transporter	<-	Objeto POP3 Transporter

Descrição

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

História

Release	Mudanças
17 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.

Estão disponíveis portos seguros:

SMTP
- 465: SMTPS
- 587 ou 25: SMTP com atualização STARTTLS se for compat[ivel com o servidor.
IMAP
- 143: IMAP non-encrypted port
- 993: IMAP com atualização STARTTLS se for compatível com o servidor
POP3
- 110: Porta não criptografada POP3
- 995: POP3 com atualização STARTTLS se suportado pelo servidor.

.authenticationMode

História

Release	Mudanças
17 R4	Adicionado

.authenticationMode : Text

Descrição

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

Por padrão, o modo mais seguro suportado pelo servidor é usado.

Valores possíveis:

Valor	Constantes	Comentário
APOP	`Autenticação POP3 APOP`	Autenticação usando o protocolo APOP (POP3 apenas)
CRAM-MD5	`POP3 authentication CRAM MD5`	Autenticação usando o protocolo CRAM-MD5
LOGIN	`POP3 authentication login`	Autenticação usando o protocolo LOGIN
OAUTH2	`POP3 authentication OAUTH2`	Autenticação usando o protocolo OAuth2
PLAIN	`Autenticação POP3 simples`	Autenticação usando o protocolo PLAIN

.checkConnection()

História

Release	Mudanças
17 R4	Adicionado

.checkConnection() : Object

Parâmetro	Tipo		Descrição
Resultados	Object	<-	Estado da ligação do objecto transportador

Descrição

The .checkConnection() function checks the connection using information stored in the transporter object, recreates the connection if necessary, and returns the status. Esta função permite verificar se os valores fornecidos pelo utilizador são válidos e consistentes.

Objeto devolvido

A função envia um pedido para o servidor de correio e devolve um objecto descrevendo o estado do correio. Este objeto pode conter as seguintes propriedades:

Propriedade		Tipo	Descrição
success		boolean	Verdadeiro se a verificação for bem sucedida, Falso de outra forma
status		number	(apenas SMTP) Código de estado devolvido pelo servidor de correio (0 no caso de um problema não relacionado com o processamento de correio)
statusText		text	Mensagem de estado devolvida pelo servidor de correio, ou último erro devolvido na pilha de erros 4D
errors		collection	pilha de erros 4D (não devolvida se for recebida uma resposta do servidor de correio)
	[ ].errCode	number	Código de erro 4D
	[ ].message	text	Descrição do erro 4D
	[ ].componentSignature	text	Assinatura da componente interna que devolveu o erro

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ória

Release	Mudanças
17 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ória

Release	Mudanças
18 R2	Adicionado

.delete( msgNumber : Integer )

Parâmetro	Tipo		Descrição
msgNumber	Integer	->	Número da mensagem que vai ser apagada

Descrição

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

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

Executar esse método não remove de verdade qualquer email. The flagged email will be deleted from the POP3 server only when the POP3_transporter object (created with POP3 New transporter) is destroyed. 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ória

Release	Mudanças
18 R2	Adicionado

.getBoxInfo() : Object

Parâmetro	Tipo		Descrição
Resultados	Object	<-	objecto boxInfo

Descrição

The .getBoxInfo() function returns a boxInfo object corresponding to the mailbox designated by the POP3 transporter. Essa função permite que recupere informação sobre o mailbox.

O objeto boxInfo retornado contém as seguintes propriedades:

Propriedade	Tipo	Descrição
mailCount	Number	Número de mensagens na caixa de email
size	Number	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ória

Release	Mudanças
20	Suporte ao parâmetro headerOnly
18 R2	Adicionado

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

Parâmetro	Tipo		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
headerOnly	Parâmetros	->	True para descarregar apenas os cabeçalhos de correio electrónico (por defeito é False)
Resultados	Object	<-	Objeto email

Descrição

The .getMail() function returns the Email object corresponding to the msgNumber in the mailbox designated by the POP3 transporter. Essa função permite manejar localmente os conteúdos de email.

Pass in msgNumber the number of the message to retrieve. Esse número é retornado na propriedade number pela função .getMailInfoList().

Optionally, you can pass true in the headerOnly parameter to exclude the body parts from the returned Email object. Somente propriedades de cabeçalhos (headers, to, from...) são então retornados. Esta opção permite-lhe optimizar a etapa de descarregamento quando muitos e-mails estão no servidor.

nota

The headerOnly option may not be supported by the server.

O método retorna Null se:

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

Objeto devolvido

.getMail() retorna um objeto email.

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ória

Release	Mudanças
18 R2	Adicionado

.getMailInfo( msgNumber : Integer ) : Object

Parâmetro	Tipo		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultados	Object	<-	mailInfo object

Descrição

The .getMailInfo() function returns a mailInfo object corresponding corresponding to the msgNumber in the mailbox designated by the POP3 transporter. Essa função permite que recupere informação sobre o email.

In msgNumber, pass the number of the message to retrieve. Esse número é retornado na propriedade number pelo método .getMailInfoList().

The mailInfo object returned contains the following properties:

Propriedade	Tipo	Descrição
size	Number	Tamanho da mensagem em bytes
id	Text	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" //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ória

Release	Mudanças
18 R2	Adicionado

.getMailInfoList() : Collection

Parâmetro	Tipo		Descrição
Resultados	Collection	<-	Coleção de objetos `mailInfo`

Descrição

The .getMailInfoList() function returns a collection of mailInfo objects describing all messages in the mailbox designated by the POP3 transporter. Essa função permite gerenciar localmente a lista de mensagens localizadas no servidor POP3.

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

Propriedade	Tipo	Descrição
[ ].size	Number	Tamanho da mensagem em bytes
[ ].number	Number	Número da mensagem
[ ].id	Text	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 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. Quando o usuário se registrar de volta no servidor, as mensagens atuais no mailbox serão numeradas de 1 a x.

The id however is a unique number assigned to the message when it was received by the server. Esse número é calculado usando a hora e data que a mensagem for recebida e é um valor atribuído ao seu servidor 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. 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ória

Release	Mudanças
18 R3	Adicionado

.getMIMEAsBlob( msgNumber : Integer ) : Blob

Parâmetro	Tipo		Descrição
msgNumber	Integer	->	Número da mensagem que na lista
Resultados	Blob	<-	Blob da string MIME retornado do servidor mail

Descrição

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. Esse número é retornado na propriedade number 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ória

Release	Mudanças
17 R5	Adicionado

.host : Text

Descrição

The .host property contains the name or the IP address of the host server. Utilizado para transacções postais (SMTP, POP3, IMAP).

.logFile

História

Release	Mudanças
17 R5	Adicionado

.logFile : Text

Descrição

The .logFile property contains the path of the extended log file defined (if any) for the mail connection. Pode ser relativo (à pasta atual de Logs) ou absoluto.

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. Para mais informações sobre arquivos de registo estendidos, consultar:

Conexões SMSTP - 4DSMTPLog.txt
Conexões POP3 - 4DPOP3Log.txt
Conexões IMAP - 4DIMAPLog.txt

.port

História

Release	Mudanças
17 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ória

Release	Mudanças
18 R2	Adicionado

.undeleteAll()

Parâmetro	Tipo		Descrição
			Não exige nenhum parâmetro

Descrição

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

.user

História

Release	Mudanças
17 R4	Adicionado

.user : Text

Descrição

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

Objeto POP3 transporter​

POP3 New transporter​

Descrição​

Resultados​

Exemplo​

4D.POP3Transporter.new()​

Descrição​

.acceptUnsecureConnection​

Descrição​

.authenticationMode​

Descrição​

.checkConnection()​

Descrição​

Objeto devolvido​

Exemplo​

.connectionTimeOut​

Descrição​

.delete()​

Descrição​

Exemplo​

.getBoxInfo()​

Descrição​

Exemplo​

.getMail()​

Descrição​

Exemplo​

.getMailInfo()​

Descrição​

Exemplo​

.getMailInfoList()​

Descrição​

número e propriedades ID​

Exemplo​

.getMIMEAsBlob()​

Descrição​

Exemplo​

.host​

Descrição​

.logFile​

Descrição​

.port​

Descrição​

.undeleteAll()​

Descrição​

.user​

Descrição​

Objeto POP3 transporter

POP3 New transporter

Descrição

Resultados

Exemplo

4D.POP3Transporter.new()

Descrição

.acceptUnsecureConnection

Descrição

.authenticationMode

Descrição

.checkConnection()

Descrição

Objeto devolvido

Exemplo

.connectionTimeOut

Descrição

.delete()

Descrição

Exemplo

.getBoxInfo()

Descrição

Exemplo

.getMail()

Descrição

Exemplo

.getMailInfo()

Descrição

Exemplo

.getMailInfoList()

Descrição

número e propriedades ID

Exemplo

.getMIMEAsBlob()

Descrição

Exemplo

.host

Descrição

.logFile

Descrição

.port

Descrição

.undeleteAll()

Descrição

.user

Descrição