Versão: v20 R4 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 Verdadeiro se 4D for permitido estabelecer uma ligação não encriptada
.authenticationMode : Text o modo de autenticação utilizado para abrir a sessão no servidor de correio
.checkConnection() : Object verifica a ligação utilizando a informação armazenada no objeto de transporte
.connectionTimeOut : Integer o tempo máximo de espera (em segundos) de uma chamada para `.send( )` antes de ocorrer um timeout
.delete( msgNumber : Integer ) assinala o e-mail msgNumber para eliminação do servidor POP3
.getBoxInfo() : Object devolve uma `boxInfo` objecto correspondente à caixa de correio designada pelo transportador `POP3`
.getMail( msgNumber : Integer ) : Object devolve o `Email` objeto correspondente ao msgNumber na caixa de correio designada pelo transportador `POP3`
.getMailInfo( msgNumber : Integer ) : Object devolve o `Email` objeto correspondente ao msgNumber na caixa de correio designada pelo transportador `POP3`
.getMailInfoList() : Collection devolve uma coleção de `mailInfo` objectos que descrevem todas as mensagens na caixa de correio designada pelo transportador `POP3`
.getMIMEAsBlob( msgNumber : Integer ) : Blob devolve um BLOB contendo o conteúdo MIME para a mensagem correspondente ao msgNumber na caixa de correio designada pelo `POP3_transporter`
.host : Text o nome ou o endereço IP do servidor anfitrião
.logFile : Text o caminho do arquivo de registo alargado definido (se existir) para a ligação de correio
.port : Integer o número do porto utilizado para as transações postais
.undeleteAll() remove todas as flags de deletar colocadas nos e-mails no `POP3_transporter`
.user : Text o nome de usuário utilizado para autenticação no servidor de correio

POP3 New transporter

Histórico

Versão	Mudanças
v18 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	<-	POP3 transporter object

Descrição

Comando POP3 New transporter configura uma nova ligação POP3de acordo com o parametro 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 Verdadeiro se 4D for permitido estabelecer uma ligação não encriptada	False
.accessTokenOAuth2: Texto .accessTokenOAuth2: Objecto Cadeia de texto ou objecto simbólico representando as credenciais de autorização do OAuth2. Usado apenas com OAUTH2 `authenticationMode`. Se `accessTokenOAuth2` for utilizado mas `authenticationMode` for omitido, é utilizado o protocolo OAuth 2 (se permitido pelo servidor). Não devolvido no objecto SMTP transporter.	nenhum
.authenticationMode : Text o modo de autenticação utilizado para abrir a sessão no servidor de correio	o modo de autenticação mais seguro disponível no servidor é usado
.connectionTimeOut : Integer o tempo máximo de espera (em segundos) de uma chamada para `.send( )` antes de ocorrer um timeout	30
.host : Text o nome ou o endereço IP do servidor anfitrião	obrigatório
.logFile : Text o caminho do arquivo de registo alargado definido (se existir) para a ligação de correio	nenhum
.password : TextUser password for authentication on the server. Não devolvido no objecto SMTP transporter.	nenhum
.port : Integer o número do porto utilizado para as transações postais	995
.user : Text o nome de usuário utilizado para autenticação no servidor de correio	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	<-	POP3 transporter object

Descrição

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

.acceptUnsecureConnection

Histórico

Versão	Mudanças
v17 R4	Adicionado

.acceptUnsecureConnection : Boolean

Descrição

A propriedade .acceptUnsecureConnection contém Verdadeiro se 4D for permitido estabelecer uma ligação não encriptada quando a ligação encriptada não é 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órico

Versão	Mudanças
v17 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órico

Versão	Mudanças
v17 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 ligação utilizando a informação armazenada no objeto de transporte, recria a ligação, se necessário, e devolve 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
    Else
       ALERT("Error: "+$status.statusText)
    End if
 End if
    Else
       ALERT("Error: "+$status.statusText)
    End if
 End if

.connectionTimeOut

Histórico

Versão	Mudanças
v17 R5	Adicionado

.connectionTimeOut : Integer

Descrição

A propriedade .sendTimeOut contém o tempo máximo de espera (em segundos) de uma chamada para .send( ) antes de ocorrer um timeout. .

.delete()

Histórico

Versão	Mudanças
v18 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( ) assinala o e-mail msgNumber para eliminação 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âmetro	Tipo		Descrição
Resultados	Object	<-	objecto boxInfo

Descrição

A função .getBoxInfo() devolve uma boxInfo objecto correspondente à caixa de correio designada pelo transportador POP3. 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	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órico

Versão	Mudanças
v20	Suporte de parâmetro headerOnly
v18 R2	Adicionado

.getMail( msgNumber : Integer ) : 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	<-	Email objecto

Descrição

A função .getMail() devolve o Email objeto correspondente ao msgNumber na caixa de correio designada pelo transportador POP3. 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().

Opcionalmente, pode passar true no parâmetro headerOnly para excluir as partes do corpo do objecto devolvido Email. Apenas as propriedades dos cabeçalhos (cabeçalhos, a, de...) são então devolvidas. 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 apagar usando .delete( ).

Objeto devolvido

.getMail() devolve um objecto 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órico

Versão	Mudanças
v18 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() devolve o Email objeto correspondente ao msgNumber na caixa de correio designada pelo transportador POP3. 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	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
 End if
 End if

.getMailInfoList()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.getMailInfoList() : Collection

Parâmetro	Tipo		Descrição
Resultados	Collection	<-	Colecção de objectos `mailInfo`

Descrição

A função .getMailInfoList() devolve uma coleção de mailInfo objectos que descrevem todas as mensagens na caixa de correio designada pelo transportador 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 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â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() devolve um BLOB contendo o conteúdo MIME para a mensagem correspondente ao msgNumber na caixa de correio designada 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

Descrição

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

.logFile

Histórico

Versão	Mudanças
v17 R5	Adicionado

.logFile : Text

Descrição

A propriedade .logFile contém o caminho do arquivo de registo alargado definido (se existir) para a ligaçã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:

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

A propriedade .port contém o número do porto utilizado para as transações postais. Por padrão, se a propriedade port não tiver sido definida no objeto server (utilizado para criar o objecto transportador com SMTP New transporter, POP3 New transporter, IMAP New transporter), a porta utilizada é:

SMTP - 587
POP3 - 995
IMAP - 993

.undeleteAll()

Histórico

Versão	Mudanças
v18 R2	Adicionado

.undeleteAll()

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

Descrição

A função .getMIMEAsBlob() remove todas as flags de deletar colocadas nos e-mails no POP3_transporter.

.user

Histórico

Versão	Mudanças
v17 R4	Adicionado

.user : Text

Descrição

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

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