Functions to notify the user application about SMTP client events. More...

Functions
uint32_t	netSMTPc_Process (netSMTPc_Request request, char buf, uint32_t buf_len, uint32_t pvar)
	Request parameters for SMTP client session. [user-provided].

void	netSMTPc_Notify (netSMTPc_Event event)
	Notify the user application when SMTP client operation ends. [user-provided].

bool	netSMTPc_AcceptAuthentication (const NET_ADDR *addr)
	Accept or deny authentication requested by SMTP server. [user-provided].

Description

Functions to notify the user application about SMTP client events.

SMTP Client user callbacks are used in legacy mode, which is started with the function netSMTPc_Connect. User callback functions are inside the user interface module SMTP_Client_UIF.c. To add the module to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the SMTP Client template. Customize this module by changing the sender's address, the recipient's address, the subject, and the body of the email message.

The following functions are available:

netSMTPc_Process - request parameters for SMTP client session (such as username, password for secure connections).
netSMTPc_Notify - notify the user application when the SMTP client operation ends.
netSMTPc_AcceptAuthentication - callback function to accept/deny the authentication advertised by SMTP Server.

Note: When SMTP Client is used with the function netSMTPc_SendMail, user callbacks are not used and interface module SMTP_Client_UIF.c can be omitted.

Function Documentation

◆ netSMTPc_AcceptAuthentication()

bool netSMTPc_AcceptAuthentication ( const NET_ADDR * addr )

Accept or deny authentication requested by SMTP server. [user-provided].

Parameters

[in] addr structure containing IP address and port of SMTP server.

Returns

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

The callback function netSMTPc_AcceptAuthentication 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 addr points to a buffer containing the IP address and port of the remote SMTP server.

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

Code Example

The following example is available in the user code template file SMTP_Client_UIF.c. Customize it to the application's needs.

bool netSMTPc_AcceptAuthentication (const NET_ADDR *addr) {
  if ((addr->addr_type == NET_ADDR_IP4) && 
      (addr->addr[0] == 192)            &&
      (addr->addr[1] == 168)            &&
      (addr->addr[2] == 0  )            &&
      (addr->addr[3] == 1  )) {
    // Deny authentication from local smtp server
    return (false);
  }
  return (true);
}

◆ netSMTPc_Notify()

void netSMTPc_Notify ( netSMTPc_Event event )

Notify the user application when SMTP client operation ends. [user-provided].

Parameters

[in] event SMTP client notification event as specified in netSMTPc_Event.

Note: Network library calls this function to inform the user about events.

The callback function netSMTPc_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 netSMTPc_Event.

The function accepts one of the following SMTP events:

Event	Description
netSMTPc_EventSuccess	The email has been sent successfully.
netSMTPc_EventTimeout	SMTP Server response has timed out, and hence the SMTP client has aborted the operation. The email has not been sent.
netSMTPc_EventAuthenticationFailed	User authentication on SMTP Server failed. The email has not been sent.
netSMTPc_EventError	Protocol error occurred while sending email. The email has not been sent.

Code Example

The following example is available in the user code template file SMTP_Client_UIF.c. Customize it to the application's needs.

// Notify the user application when SMTP client operation ends.
void netSMTPc_Notify (netSMTPc_Event event) {
  switch (event) {
    case netSMTPc_EventSuccess:
      // Email successfully sent
      break;
 
    case netSMTPc_EventTimeout:
      // Timeout sending email
      break;
 
    case netSMTPc_EventAuthenticationFailed:
      // User authentication failed
      break;
 
    case netSMTPc_EventError:
      // Error when sending email
      break;
  }
}

◆ netSMTPc_Process()

uint32_t netSMTPc_Process	(	netSMTPc_Request	request,
		char *	buf,
		uint32_t	buf_len,
		uint32_t *	pvar
	)

Request parameters for SMTP client session. [user-provided].

Parameters

[in]	request	request code.
[out]	buf	output buffer to write the data to.
[in]	buf_len	length of the output buffer in bytes.
[in,out]	pvar	pointer to a session's local buffer of 4 bytes. 1st call = cleared 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.

return len | (1u<<31) = repeat flag, the system calls this function again when request is netSMTPc_RequestBody.

The callback function netSMTPc_Process provides additional parameters for the SMTP client session such as the credentials to login to the SMTP server, email address of the sender and recipient, etc. The SMTP client calls this function several times to complete sending an email.

The argument request is an SMTP client signal:

Request Name	Description
netSMTPc_RequestUsername	Username to login to SMTP server
netSMTPc_RequestPassword	Password to login to SMTP server
netSMTPc_RequestSender	Email address of the sender
netSMTPc_RequestRecipient	Email address of the recipient
netSMTPc_RequestSubject	Subject of email
netSMTPc_RequestBody	Email body in plain ASCII format

The argument buf points to the output buffer where the function writes the requested data.

The argument buf_len specifies the length of the output buffer in bytes.

The argument pvar points to the local session buffer with a length of 4 bytes. The SMTP Client clears the data in the pvar pointer to 0 before the function is called for the first time.

Code Example

The following example is available in the user code template file SMTP_Client_UIF.c. Customize it to the application's needs.

// Request parameters for SMTP client session.
uint32_t netSMTPc_Process (netSMTPc_Request request, char *buf, uint32_t buf_len, uint32_t *pvar) {
  uint32_t len = 0;
 
  switch (request) {
    case netSMTPc_RequestUsername:
      // Username to login to SMTP server
      len = sprintf (buf, "guest");
      break;
 
    case netSMTPc_RequestPassword:
      // Password to login to SMTP server
      len = sprintf (buf, "guest");
      break;
 
    case netSMTPc_RequestSender:
      // Email address of the sender
      len = sprintf (buf, "me@domain.com");
      break;
 
    case netSMTPc_RequestRecipient:
      // Email address of the recipient
      len = sprintf (buf, "you@domain.com");
      break;
 
    case netSMTPc_RequestSubject:
      // Subject of email
      len = sprintf (buf, "Hello");
      break;
 
    case netSMTPc_RequestBody:
      // Email body in plain ascii format
      len = sprintf (buf, "Hello, how are you?\r\n");
  }
  return (len);
}