SMTPTransporter

A classe SMTPTransporter permite-lhe configurar ligações SMTP e enviar correios eletrónicos através de SMTP transpor ter objetos.

Objecto SMTP Transporter

Os objectos do SMTP Transporter são instanciados com o comando SMTP New Transportter. 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
.bodyCharset : Text     o charset e a codificação utilizados para a parte do corpo do e-mail
.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) permitido para estabelecer uma conexão com o servidor
.headerCharset : Text     o charset e a codificação utilizados para o cabeçalho do correio eletrônico
.host : Text    o nome ou o endereço IP do servidor anfitrião
.keepAlive : Boolean    True se a ligação SMTP tiver de ser mantida viva até que o objeto transportador seja destruído
.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
.send( mail : Object ) : Object    envia o mail ** objecto para o servidor SMTP definido no objecto transportador e devolve um objecto de estado
.sendTimeOut : Integer     o tempo máximo de espera (em segundos) de uma chamada para .send( ) antes de ocorrer um timeout
.user : Text     o nome de usuário utilizado para autenticação no servidor de correio

SMTP New transporter

Histórico

Versão	Mudanças
v18	Nova propriedade logFile
v17 R5	Novas propriedades bodyCharset e headerCharset
v17 R4	Adicionado

SMTP New transporter( server : Object ) : 4D.SMTPTransporter

Parâmetros	Tipo		Descrição
server	Objeto	->	Informação de servidor de correio
Resultados	4D.SMTPTransporter	<-	SMTP transporter

Descrição

O comando SMTP New transporter configura uma nova ligação SMTP de acordo com o parametro server e retorna um novo objetoSMTP transporter. Summary -->sends the mail object to the SMTP server defined in the transporter object and returns a status object.

Este comando não abre qualquer ligação com o servidor SMTP. A ligação SMTP é efectivamente aberta quando a função .send() é executada.

A coleção SMTP é automaticamente fechada:

• quando o objecto transportador é destruído se a propriedade keepAlive for true (por defeito),
• após cada execução da função .send( ) se a propriedade keepAlive estiver configurada para false.

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). Text string or token object representing OAuth2 authorization credentials.	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
.bodyCharset : Text     o charset e a codificação utilizados para a parte do corpo do e-mail	mail mode UTF8 (US-ASCII_UTF8_QP)
.connectionTimeOut : Integer    o tempo máximo de espera (em segundos) permitido para estabelecer uma conexão com o servidor	30
.headerCharset : Text     o charset e a codificação utilizados para o cabeçalho do correio eletrônico	mail mode UTF8 (US-ASCII_UTF8_QP)
.host : Text    o nome ou o endereço IP do servidor anfitrião	obrigatório
.keepAlive : Boolean    True se a ligação SMTP tiver de ser mantida viva até que o objeto transportador seja destruído	True
.logFile : Text    o caminho do arquivo de registo alargado definido (se existir) para a ligação de correio	nenhum
password: Text senha de usuário para autenticação no servidor. Text string or token object representing OAuth2 authorization credentials.	nenhum
.port : Integer     o número do porto utilizado para as transações postais	587
.sendTimeOut : Integer     o tempo máximo de espera (em segundos) de uma chamada para .send( ) antes de ocorrer um timeout	100
.user : Text     o nome de usuário utilizado para autenticação no servidor de correio	nenhum

Resultados

A função devolve um objecto SMTP transporter. Todas as propriedades retornadas são apenas leitura.

Exemplo

 $server:=New object
 $server.host:="smtp.gmail.com" //Obrigatório
 $server.port:=465
 $server.user:="4D@gmail.com"
 $server.password:="XXXX"
 $server.logFile:="LogTest.txt" //Histórico extenso para salvar na pasta Logs

 var $transporter : 4D.SMTPTransporter
 $transporter:=SMTP New transporter($server)

 $email:=New object
 $email.subject:="my first mail "
 $email.from:="4d@gmail.com"
 $email.to:="4d@4d.com;test@4d.com"
 $email.textBody:="Hello World"
 $email.htmlBody:="<h1>Hello World</h1><h4>'Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...'</h4>\
 <p>There are many variations of passages of Lorem Ipsum available."\
 +"The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</p>"

 $status:=$transporter.send($email)
 If(Not($status.success))
    ALERT("An error occurred sending the mail: "+$status.message)
 End if

4D.SMTPTransporter.new()

4D.SMTPTransporter.new( server : Object ) : 4D.SMTPTransporter

Parâmetros	Tipo		Descrição
server	Objeto	->	Informação de servidor de correio
Resultados	4D.SMTPTransporter	<-	SMTP transporter

Descrição

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

.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:

Value	Constantes	Comentário
CRAM-MD5	SMTP authentication CRAM MD5	Autenticação usando o protocolo CRAM-MD5
LOGIN	SMTP authentication login	Autenticação usando o protocolo LOGIN
OAUTH2	SMTP authentication OAUTH2	Autenticação usando o protocolo OAuth2
PLAIN	SMTP authentication plain	Autenticação usando o protocolo PLAIN

.bodyCharset

Histórico

Versão	Mudanças
v18	Suporte de UTF8 base64
v17 R5	Adicionado

.bodyCharset : Text

Descrição

A propriedade .bodyCharset contém o charset e a codificação utilizados para a parte do corpo do e-mail.

Valores possíveis:

Constante	Value	Comentário
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset: US-ASCII se for possível, japonês (ISO-2022-JP) & Quoted-printable se for possível, do contrário UTF-8 & Quoted-printable bodyCharset: US-ASCII se possível, japonês (ISO-2022-JP) e 7 bits se for possível, do contrário UTF-8 & Quoted-printable
mail mode ISO88591	ISO-8859-1	headerCharset: ISO-8859-1 & Quoted-printable bodyCharset: ISO-8859-1 & 8-bit
mail mode UTF8	US-ASCII_UTF8_QP	headerCharset & bodyCharset: US-ASCII se possível, caso contrário UTF-8 & Quoted-printable (valor por defeito)
modo de correio UTF8 na base64	US-ASCII_UTF8_B64	headerCharset & bodyCharset: US-ASCII se possível, senão UTF-8 & base64

.checkConnection()

Histórico

Versão	Mudanças
v17 R4	Adicionado

.checkConnection() : Object

Parâmetros	Tipo		Descrição
Resultados	Objeto	<-	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

Para informações sobre códigos de estado SMTP, consulte por favor esta página.

Exemplo

 var $pw : Text
 var $options : Object
 var $transporter : 4D.SMTPTransporter
 $options:=New object

 $pw:=Request("Please enter your password:")
 $options.host:="smtp.gmail.com"

 $options.user:="test@gmail.com"
 $options.password:=$pw

 $transporter:=SMTP New transporter($options)

 $status:=$transporter.checkConnection()
 If($status.success=True)
    ALERT("SMTP connection check successful!")
 Else
    ALERT("Error # "+String($status.status)+", "+$status.statusText)
 End if
 Else
    ALERT("Error # "+String($status.status)+", "+$status.statusText)
 End if

.connectionTimeOut

Histórico

Versão	Mudanças
v17 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 objecto servidor (utilizado para criar o objecto transportador com SMTP Novo transportador, POP3 Novo transportador, ou IMAP Novo transportador), o valor é 30.

.headerCharset

Histórico

Versão	Mudanças
v17 R5	Adicionado

.headerCharset : Text

Descrição

A propriedade .headerCharset contém o charset e a codificação utilizados para o cabeçalho do correio eletrônico. O cabeçalho inclui as seguintes partes do e-mail:

• subject,
• nome(s) de arquivo anexo,
• email name.

Valores possíveis:

Constante	Value	Comentário
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset: US-ASCII se for possível, japonês (ISO-2022-JP) & Quoted-printable se for possível, do contrário UTF-8 & Quoted-printable bodyCharset: US-ASCII se possível, japonês (ISO-2022-JP) e 7 bits se for possível, do contrário UTF-8 & Quoted-printable
mail mode ISO88591	ISO-8859-1	headerCharset: ISO-8859-1 & Quoted-printable bodyCharset: ISO-8859-1 & 8-bit
mail mode UTF8	US-ASCII_UTF8_QP	texto
modo de correio UTF8 na base64	US-ASCII_UTF8_B64	headerCharset & bodyCharset: US-ASCII se possível, senão UTF-8 & base64

.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).

.keepAlive

Histórico

Versão	Mudanças
v17 R4	Adicionado

.keepAlive : Boolean

Descrição

A propriedade .keepAlive contém True se a ligação SMTP tiver de ser mantida viva até que o objeto transportador seja destruído, e Falso caso contrário. Por padrão, se a propriedade keepAlive não foi definida no objecto server (utilizado para criar o objecto transporter com SMTP New transporter), este é True.

A coleção SMTP é automaticamente fechada:

• quando o objecto transporter for destruído se a propriedade .keepAlive for true,
• após cada execução da função .send( ) se a propriedade .keepAlive estiver configurada para false.

.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:

• Conexões SMTP - 4DSMTPLog.txt
• Conexões POP3 - 4DPOP3Log.txt
• Conexões IMAP - 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 não tiver sido definida no objeto servidor (utilizado para criar o objecto transportador com SMTP Novo transportador, POP3 Novo transportador, ou IMAP Novo transportador), o valor é 30:

• SMTP - 587
• POP3 - 995
• IMAP - 993

.send()

Histórico

Versão	Mudanças
v17 R5	Suporte de conteúdo Mime
v17 R4	Adicionado

.send( mail : Object ) : Object

Parâmetros	Tipo		Descrição
mail	Objeto	->	Email para enviar
Resultados	Objeto	<-	Status SMTP

Descrição

A função .send() envia o mail ** objecto para o servidor SMTP definido no objecto transportador e devolve um objecto de estado.

O objeto transportador já deve ter sido criado usando o comando SMTP New transporter .

O método cria a ligação SMTP se esta ainda não estiver viva. Se a propriedade .keepAlive do transportador for falso, a ligação SMTP é automaticamente fechada após a execução de .send(), caso contrário permanece viva até que o objecto do transportador seja destruído. Para mais informações, consultar o SMTP New Transportter descrição do comando.

Em mail, passe um e-mail válido Email object para enviar. As propriedades de origem (de onde vem o e-mail) e de destino (um ou mais destinatários) devem ser incluídas, as restantes propriedades são opcionais.

Objeto devolvido

A função devolve um objecto que descreve o estado SMTP da operação. Este objeto pode conter as seguintes propriedades:

Propriedade	Tipo	Descrição
success	boolean	Verdadeiro se o envio for bem sucedido, False caso contrário
status	number	Código de estado devolvido pelo servidor SMTP (0 no caso de um problema não relacionado com o processamento de correio)
statusText	text	Mensagem de estado devolvida pelo servidor SMTP

No caso de um problema não relacionado com o processamento SMTP (por exemplo, falta uma propriedade obrigatória no correio), 4D gera um erro que pode ser interceptado utilizando um método instalado pelo comando ON ERR CALL . Utilizar o comando GET LAST ERROR STACK para informações sobre o erro.

Neste caso, o objecto de estatuto resultante contém os seguintes valores:

Propriedade	Value
success	False
status	0
statusText	"Failed to send email"

.sendTimeOut

Histórico

Versão	Mudanças
v17 R4	Adicionado

.sendTimeOut : 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. .

.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.