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 | <- | POP3 transporter object |
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.
In the server parameter, pass an object containing the following properties:
server | Valor padrão (se omitido) |
---|---|
.acceptUnsecureConnection : Boolean True if 4D is allowed to establish an unencrypted connection | False |
.accessTokenOAuth2: Text .accessTokenOAuth2: Object Text string or token object representing OAuth2 authorization credentials. Used only with OAUTH2 authenticationMode . If accessTokenOAuth2 is used but authenticationMode is omitted, the OAuth 2 protocol is used (if allowed by the server). Not returned in SMTP transporter object. | 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 User password for authentication on the server. Not returned in SMTP transporter object. | 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 | <- | POP3 transporter object |
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.
In the msgNumber parameter, pass the number of the email to delete. This number is returned in the number property by the .getMailInfoList()
method.
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. The flag could be also be removed using the .undeleteAll()
method.
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.
The boxInfo
object returned contains the following properties:
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 | <- | Email object |
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. This number is returned in the number
property by the .getMailInfoList()
function.
Optionally, you can pass true
in the headerOnly parameter to exclude the body parts from the returned Email
object. Only headers properties (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.
The headerOnly option may not be supported by the server.
O método retorna Null se:
- msgNumber determina uma mensagem não existente,
- the message was marked for deletion using
.delete()
.
Objeto devolvido
.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ó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. This number is returned in the number property by the .getMailInfoList()
method.
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,
- the message was marked for deletion using
.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. This number is returned in the number property by the .getMailInfoList()
method.
O método retorna uma BLOB vazia se:
- msgNumber determina uma mensagem não existente,
- the message was marked for deletion using
.delete()
.
BLOB devolvido
.getMIMEAsBlob()
returns a BLOB
which can be archived in a database or converted to an Email
object with the MAIL Convert from MIME
command.
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:
- SMTP connections - 4DSMTPLog.txt
- POP3 connections - 4DPOP3Log.txt
- IMAP connections - 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.