Control Interface

Functions to connect to an SMTP server. More...

Functions
netStatus	netSMTPc_Connect (const NET_ADDR *addr)
	Start SMTP client to send an email in legacy mode. [thread-safe]. More...
netStatus	netSMTPc_SendMail (const NET_SMTP_MAIL *mail, const NET_SMTP_MTA *mta)
	Send an email in blocking mode. [thread-safe]. More...

Description

Functions to connect to an SMTP server.

The SMTP Client supports two modes of operation. Mode of operation is selected with the function, which is used to send an email. The following are available:

• netSMTPc_SendMail function starts blocking mode,
  
• netSMTPc_Connect function starts legacy mode.

The blocking mode starts with a call to netSMTPc_SendMail function. In this mode user callbacks are not used. The calling function is blocked until the operation completes and then returns the state of the operation. The blocking mode supports additional features, which are not available in legacy mode:

• multiple email recipients,
• additional address friendly names,
• encoding support for non ascii characters (ie. utf-8),
• email attachments.

When the netSMTPc_SendMail function is called, the SMTP client resolves the IP address from the specified server name and opens a SMTP connection to the server. After handshaking, the SMTP Client transmits the message content. If the email attachments are specified, the client composes a multipart MIME message with the attachments. If you want to send an email with the attachment, you have to enable SMTP Client (full variant) in µVision configuration and specify file name(s) to attach.

The legacy mode starts with a connect request using netSMTPc_Connect. The SMTP client then opens a SMTP connection to the specified server. The user application then needs to wait for the callback function netSMTPc_Notify to return the state of the operation. Based on the callback event, further processing can be started.

Function Documentation

netSMTPc_Connect()

netStatus netSMTPc_Connect

(

const NET_ADDR *

addr

)

Start SMTP client to send an email in legacy mode. [thread-safe].

Parameters

[in]

addr

structure containing IP address and port of SMTP server.

Returns

status code that indicates the execution status of the function.

The function netSMTPc_Connect starts the SMTP client. The SMTP client then connects to an SMTP server specified with the argument addr which points to a buffer containing the IP address and port of the SMTP server. If the specified port is 0, the client uses a standard SMTP server port 25 to connect to the server.

Possible netStatus return values:

• netOK: Mail client started successfully.
• netInvalidParameter: Invalid SMTP server address provided.
• netWrongState: Mail client is busy.

Note

The function netSMTPc_Connect is deprecated, use the netSMTPc_SendMail function instead.

Code Example

const NET_ADDR4 smtp_server = { NET_ADDR_IP4, 0, 192, 168, 0, 253 };
 ..
// Start SMTP client, use default SMTP port
if (netSMTPc_Connect ((NET_ADDR *)&smtp_server) != netOK) {
  // Failed to start SMTP process
}

netSMTPc_SendMail()

netStatus netSMTPc_SendMail	(	const NET_SMTP_MAIL *	mail,
		const NET_SMTP_MTA *	mta
	)

Send an email in blocking mode. [thread-safe].

Parameters

[in]	mail	pointer to email content descriptor.
[in]	mta	pointer to mail transfer agent descriptor.

Returns

status code that indicates the execution status of the function.

The function netSMTPc_SendMail sends an email in blocking mode. The function blocks the calling thread and returns, when an email is sent. The function resolves server IP address from the host name, connects to the server and sends an email.

The argument mail points to a structure that contains a description of an email to send. All entries in a structure are pointers to null-terminated strings. When more parameters are specified (for example several To addresses), use a semicolon ';' character as a parameter separator.

The argument mta points to a structure with mail transfer agent parameters. This structure contains SMTP server address, port number, flags and user credentials for authentication. Server address can be either a fully qualified domain name or an IP address presented in string format.

Possible netStatus return values:

• netOK: Operation completed successfully.
• netInvalidParameter: Invalid or not supported parameter provided.
• netWrongState: Mail client is busy.
• netDnsResolverError: DNS host resolver failed.
• netServerError: Mail server failed.
• netAuthenticationFailed: User credentials are not valid.
• netFileError: Requested mail attachment is not existing.
• netError: Mail client internal error.

Note

To use this function, you must enable the DNS client in the selection of RTE Components.

Code Example (multiple recipients and friendly names)

NET_SMTP_MAIL mail;
NET_SMTP_MTA  server;
char buffer[200];
 ..
mail.From       = "John <john@example.net>";
mail.To         = "Mary <mary@example.net>; Joe <joe@example.net>"; 
mail.Cc         = "Tony <tony@example.net>";
mail.Bcc        = "Support<support@example.net>";
mail.Subject    = "Mail demo";
mail.Message    = buffer;
mail.Attachment = NULL;
mail.Encoding   = NULL;
 
sprintf (buffer, "%s", "Hello from SMTP client!");
 
server.Address  = "mail.example.net";
server.Port     = 0;
server.Flags    = 0;
server.Username = "my_username";
server.Password = "my_password";
 
// Send mail, use default SMTP port
if (netSMTPc_SendMail (&mail, &server) != netOK) {
  // Failed to send an email
}

Code Example (utf-8 encoding for 'µ' character)

const NET_SMTP_MAIL mail = {
  "john@example.net",            // From
  "mary@example.net",            // To 
  NULL,                          // Cc
  NULL,                          // Bcc
  "µVision test",                // Subject
  "Here is µVision test log!",   // Message
  NULL,                          // Attachment
  "utf-8"                        // Encoding
};