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
| 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 | <- | POP3 transporter object |
|
Descrição
Comando POP3 New transporter configura uma nova ligação POP3de acordo com o parametro server e retorna um novo objeto*POP3 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
| Release | Mudanças |
|---|---|
| 17 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
| 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 | Autenticação POP3 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
| 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 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
| Release | Mudanças |
|---|---|
| 17 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
| 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( ) 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
| Release | Mudanças |
|---|---|
| 18 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
| Release | Mudanças |
|---|---|
| 20 | Suporte de parâmetro headerOnly |
| 18 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.
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
| 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() 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
| Release | Mudanças |
|---|---|
| 18 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
| 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() 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
| Release | Mudanças |
|---|---|
| 17 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
| Release | Mudanças |
|---|---|
| 17 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
| Release | Mudanças |
|---|---|
| 17 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
| Release | Mudanças |
|---|---|
| 18 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
| Release | Mudanças |
|---|---|
| 17 R4 | Adicionado |
.user : Text
Descrição
A propriedade .user contém o nome de usuário utilizado para autenticação no servidor de correio.