Versão: 20 R9 BETA

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 se o 4D tiver permissão para estabelecer uma conexão não criptografada
.authenticationMode : Text o modo de autenticação usado para abrir a sessão no servidor de e-mail
.checkConnection() : Object verifica a conexão usando as informações armazenadas no objeto transportador
.connectionTimeOut : Integer o tempo máximo de espera (em segundos) permitido para estabelecer uma conexão com o servidor
.delete( msgNumber : Integer ) flags do e-mail msgNumber para exclusão do servidor POP3
.getBoxInfo() : Object retorna um objeto `boxInfo` correspondente à caixa de correio designada pelo `transporter POP3`
.getMail( msgNumber : Integer { ; headerOnly : Boolean } ) : Object retorna o objeto `Email` correspondente ao msgNumber na caixa de correio designada pelo `transporter POP3`
.getMailInfo( msgNumber : Integer ) : Object retorna um objeto `mailInfo` correspondente ao msgNumber na caixa de correio designada pelo `transporter POP3`
.getMailInfoList() : Collection retorna uma coleção de objetos `mailInfo` descrevendo todas as mensagens na caixa de correio designada pelo `transporter POP3`
.getMIMEAsBlob( msgNumber : Integer ) : Blob retorna um BLOB contendo o conteúdo MIME da mensagem correspondente ao msgNumber na caixa de correio designada pelo `POP3_transportter`
.host : Text o nome ou o endereço IP do servidor host
.logFile : Text o caminho do arquivo de registro estendido definido (se houver) para a conexão de correio
.port : Integer o número da porta utilizada para transações de email
.undeleteAll() remove todos os sinalizadores de exclusão definidos nos e-mails no `POP3_transporter`
.port : Integer o número da porta utilizada para transações de email

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

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

.acceptUnsecureConnection

História

Release	Mudanças
17 R4	Adicionado

.acceptUnsecureConnection : Boolean

Descrição

A propriedade .acceptUnsecureConnection contém True se o 4D tiver permissão para estabelecer uma conexão não criptografada quando a conexão criptografada não for possível.

Contém False se conexões cifradas não forem permitidas, neste caso um erro é retornado quando a conexão criptografada não for possível.

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

A propriedade .authenticationMode contém o modo de autenticação utilizado para abrir a sessão no servidor de correio.

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

A função .checkConnection() verifica a conexão usando as informações armazenadas no objeto transportador, recria a conexão, se necessário, e retorna o estado. 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

A propriedade .connectionTimeOut contém o tempo máximo de espera (em segundos) permitido para estabelecer uma conexão com o servidor. Por padrão, se a propriedade não tiver sido definida no objeto do servidor (usado para criar o objeto do transportador com SMTP New transporter, POP3 New transporter ou IMAP New transporter), o valor será 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

A função .delete( ) flags do e-mail msgNumber para exclusão do servidor POP3 .

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. O email marcado será apagado do servidor POP3 apenas quando o POP3_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ória

Release	Mudanças
18 R2	Adicionado

.getBoxInfo() : Object

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

Descrição

A função .getBoxInfo() retorna um objeto boxInfo correspondente à caixa de correio designada pelo transporter POP3 . 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

A função .getMail() retorna o objeto Email correspondente ao msgNumber na caixa de correio designada pelo transporter POP3. Essa função permite manejar localmente os conteúdos de email.

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

Opcionalmente, você pode passar true no parâmetro headerOnly para excluir as partes do corpo do objeto Email retornado. 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

A opção headerOnly pode não ser suportada pelo servidor.

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

A função .getMailInfo() retorna um objeto mailInfo correspondente ao msgNumber na caixa de correio designada pelo transporter POP3. Essa função permite que recupere informação sobre o email.

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

O objeto mailInfo retornado contém as funcionalidades abaixo:

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" //Obrigatório
 $server.port:=995
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

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

  //informações da mensagem
 $mailInfo:=$transporter.getMailInfo(1) //receber a primeira correspondência
 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

A função .getMailInfoList() retorna uma coleção de objetos mailInfo descrevendo todas as mensagens na caixa de correio designada pelo transporter POP3 . 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	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 é o número de uma mensagem no mailbox no momento em quePOP3_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 o tempo de vida do objeto 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ó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

A função .getMIMEAsBlob() retorna um BLOB contendo o conteúdo MIME da mensagem correspondente ao msgNumber na caixa de correio designada pelo POP3_transportter.

Passe em msgNumber o número da mensagem a recuperar. 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

A propriedade .host contém o nome ou o endereço IP do servidor host. Utilizado para transacções postais (SMTP, POP3, IMAP).

.logFile

História

Release	Mudanças
17 R5	Adicionado

.logFile : Text

Descrição

A propriedade .logFile contém o caminho do arquivo de registro estendido definido (se houver) para a conexão de correio. Pode ser relativo (à pasta atual de Logs) ou absoluto.

Ao contrário dos arquivos de registo regulares (ativados através do comando SET DATABASE PARAMETER), os arquivos de registo armazenam o conteúdo MIME de todos os e-mails enviados e não têm qualquer limite de tamanho. 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

A propriedade .port contém o número da porta utilizada para transações de email. Por padrão, se a propriedade port não tiver sido definida no objeto server (usado para criar o objeto transportador com SMTP New transporter, POP3 New transporter, IMAP New transporter), a porta usada será:

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

A função .undeleteAll() remove todos os sinalizadores de exclusão definidos nos e-mails no POP3_transporter.

.user

História

Release	Mudanças
17 R4	Adicionado

.user : Text

Descrição

A propriedade .user contém o nome de usuário usado para autenticação no servidor de email .

Objeto POP3 transporter​

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

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