SMTP Client

SMTP Client routines allow sending of e-mail notifications using a SMTP server. More...

Functions
bool	smtp_client_accept_authentication (const uint8_t *ip_addr)
	Accept or deny authentication requested by SMTP server.
netStatus	smtp_client_connect (const uint8_t *ip_addr, uint16_t port)
	Start SMTP client to send an email.
uint32_t	smtp_client_request (smtpClientRequest request, char *buf, uint32_t buflen, uint32_t *pvar)
	Request parameters for SMTP client session.
void	smtp_client_notify (smtpClientEvent event)
	Notify the user application when SMTP client operation ends.
enum	smtpClientRequest {   smtpClientUsername,   smtpClientPassword,   smtpClientSender,   smtpClientRecipient,   smtpClientSubject,   smtpClientBody }
	SMTP Client Request. More...
enum	smtpClientEvent {   smtpClientSuccess = 0,   smtpClientTimeout,   smtpClientError }
	SMTP Client Events. More...

Description

SMTP Client routines allow sending of e-mail notifications using a SMTP server.

Simple Mail Transfer Protocol (SMTP) is a widely used protocol for the delivery of e-mails between TCP/IP systems and users.

A SMTP Client can send e-mails to various recipients. A typical use is to send automated e-mail notifications to different e-mail addresses.

Note

The page SMTP Client gives you more information on the actual usage of the functions and how to work with them in a project.

Code Examples

SMTP Client User Interface Template

The following source code is part of the SMTP_Client_UIF.c template file. This code template enables the developer to create an application specific callback function. Also, user authentication for a specific SMTP server can be enabled or disabled:

#include <stdio.h>
#include "rl_net.h"
 
// Request parameters for SMTP client session.
uint32_t smtp_client_request (smtpClientRequest request, char *buf, uint32_t buflen, uint32_t *pvar) {
  uint32_t len = 0;
 
  switch (request) {
    case smtpClientUsername:
      // Username to login to SMTP server
      /* Example
      len = sprintf (buf, "guest");
      */
      break;

    case smtpClientPassword:
      // Password to login to SMTP server
      /* Example
      len = sprintf (buf, "guest");
      */
      break;

    case smtpClientSender:
      // Email address of the sender
      /* Example
      len = sprintf (buf, "me@domain.com");
      */
      break;

    case smtpClientRecipient:
      // Email address of the recipient
      /* Example
      len = sprintf (buf, "you@domain.com");
      */
      break;

    case smtpClientSubject:
      // Subject of email
      /* Example
      len = sprintf (buf, "Hello");
      */
      break;

    case smtpClientBody:
      // Email body in plain ascii format
      /* Example
      len = sprintf (buf, "Hello, how are you?\r\n");
      */
      break;
  }
  return (len);
}
 
// Notify the user application when SMTP client operation ends.
void smtp_client_notify (smtpClientEvent event) {
  switch (event) {
    case smtpClientSuccess:
      // Email successfully sent
      break;
    case smtpClientTimeout:
      // Timeout sending email
      break;
    case smtpClientError:
      // Error when sending email
      break;
  }
}
 
// Accept or deny authentication requested by SMTP server.
bool smtp_client_accept_authentication (const uint8_t *ip_addr) {
  /* Example
  if (ip_addr[0] == 192  &&
      ip_addr[1] == 168  &&
      ip_addr[2] == 0    &&
      ip_addr[3] == 1) {
    // Deny authentication from local smtp server
    return (false);
  }
  */
  return (true);
}

Enumeration Type Documentation

enum smtpClientEvent

SMTP Client Events.

Parameter for:

• smtp_client_notify

Enumerator:

smtpClientSuccess	Email successfully sent.
smtpClientTimeout	Timeout sending email.
smtpClientError	Error when sending email.

enum smtpClientRequest

SMTP Client Request.

Parameter for:

• smtp_client_request

Enumerator:

smtpClientUsername	Username to login to SMTP server.
smtpClientPassword	Password to login to SMTP server.
smtpClientSender	Email address of the sender.
smtpClientRecipient	Email address of the recipient.
smtpClientSubject	Subject of email.
smtpClientBody	Email body in plain ASCII format.

Function Documentation

bool smtp_client_accept_authentication

(

const uint8_t *

ip_addr

)

Accept or deny authentication requested by SMTP server.

Parameters

[in]

ip_addr

IP address of the remote SMTP server.

Returns

• true = Authentication is accepted.
• false = Authentication is denied.

The function smtp_client_accept_authentication informs the Network Component if the SMTP client should log on to a SMTP Server when sending e-mails. The Network Component library calls this function and asks the user what to do if the SMTP Server has advertised the user authentication. It is now on the user to accept the authentication.

The argument ip_addr points to a buffer containing the four octets that make up the IP address of the remote SMTP server.

You can customize the function in the file SMTP_Client_UIF.c.

Note

This function is called if the SMTP server has advertised user authentication.

Code Example

// Accept or deny authentication requested by SMTP server.
bool smtp_client_accept_authentication (const uint8_t *ip_addr) {
  if (ip_addr[0] == 192  &&
      ip_addr[1] == 168  &&
      ip_addr[2] == 0    &&
      ip_addr[3] == 1) {
    // Deny authentication from local smtp server
    return (false);
  }
  return (true);
}

netStatus smtp_client_connect	(	const uint8_t *	ip_addr,
		uint16_t	port
	)

Start SMTP client to send an email.

Parameters

[in]	ip_addr	IP address of the SMTP server.
[in]	port	port number of SMTP server.

Returns

status code that indicates the execution status of the function as defined with netStatus.

The function smtp_client_connect starts the SMTP client and tries to connect to an SMTP server specified by ip_addr on the TCP port port.

The argument ip_addr points to the IP address of the SMTP server.

The argument port points to TCP port of the SMTP server.

Note

• The standard SMTP port is TCP port 25.
• An application can call the smtp_client_connect function to connect to an SMTP server to send emails.

Code Example

...
  // Start SMTP client, use default SMTP port
  retv = smtp_client_connect (srv_ip, 0);
  if (retv != netOK) {
    // Failed to start SMTP process
  }

void smtp_client_notify

(

smtpClientEvent

event

)

Notify the user application when SMTP client operation ends.

Parameters

[in]

event

SMTP client notification event

Returns

none.

Note

This function is called by the system to inform about events.

The function smtp_client_notify is called automatically when a SMTP event occurred and notifies the user application when the SMTP client operation ends.

The argument event is an SMTP client signal as defined in smtpClientEvent.

The function takes one of the following SMTP events:

Event	Description
smtpClientSuccess	The email has been sent successfully.
smtpClientTimeout	SMTP Server response has timed out, and hence the SMTP client has aborted the operation. The email has not been sent.
smtpClientError	Protocol error occurred while sending email. The email has not been sent.

You can customize the function in SMTP_Client_UIF.c.

Code Example

#include <stdio.h>
#include "rl_net.h"
 
// Notify the user application when SMTP client operation ends.
void smtp_client_notify (smtpClientEvent event) {
  switch (event) {
    case smtpClientSuccess:
      // Email successfully sent
      break;
    case smtpClientTimeout:
      // Timeout sending email
      break;
    case smtpClientError:
      // Error when sending email
      break;
  }
}

uint32_t smtp_client_request	(	smtpClientRequest	request,
		char *	buf,
		uint32_t	buflen,
		uint32_t *	pvar
	)

Request parameters for SMTP client session.

Parameters

[in]	request	request code.
[out]	buf	output buffer to write the data to.
[in]	buflen	length of the output buffer in bytes.
[in,out]	pvar	pointer to a session's local buffer of 4 bytes. 1st call = set to 0, 2nd call = not altered by the system, 3rd call = not altered by the system, etc.

Returns

number of bytes written to output buffer.

The function smtp_client_request sends a client request to the SMTP server and returns the actual number of bytes written to the output buffer buf.

The argument request is an SMTP client signal as defined in smtpClientRequest.

The argument buf points to the buffer to which data are written. The argument buflen is the buf data length in bytes.

The argument pvar points to the local session buffer with a length of 4 bytes.

You can customize the function in SMTP_Client_UIF.c.

Note

• The length of the output buffer, buflen might vary because buffer length is determined by the TCP socket Maximum Segment Size (MSS) negotiation. It is normally around 1400 bytes for local LAN. But this can be reduced to 500 bytes or even less.
• If the smtp_client_request function writes more bytes than buflen into the output buffer, then a system crash resulting from corruption of memory link pointers is highly likely.
• The argument pvar is private to each SMTP Session. The SMTP Client clears the data in the pvar pointer to 0 before the function is called for the first time.

Code Example

#include <stdio.h>
#include "rl_net.h"
 
// Request parameters for SMTP client session.
uint32_t smtp_client_request (smtpClientRequest request, char *buf, uint32_t buflen, uint32_t *pvar) {
  uint32_t len = 0;
 
  switch (request) {
    case smtpClientUsername:
      // Username to login to SMTP server
      len = sprintf (buf, "guest");
      break;

    case smtpClientPassword:
      // Password to login to SMTP server
      len = sprintf (buf, "guest");
      break;

    case smtpClientSender:
      // Email address of the sender
      len = sprintf (buf, "me@domain.com");
      break;

    case smtpClientRecipient:
      // Email address of the recipient
      len = sprintf (buf, "you@domain.com");
      break;

    case smtpClientSubject:
      // Subject of email
      len = sprintf (buf, "Hello");
      break;

    case smtpClientBody:
      // Email body in plain ascii format
      len = sprintf (buf, "Hello, how are you?\r\n");
      break;
  }
  return (len);
}