Network Component  Version 7.19.0
MDK Middleware for IPv4 and IPv6 Networking
User Callbacks

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]. More...
 
void netSMTPc_Notify (netSMTPc_Event event)
 Notify the user application when SMTP client operation ends. [user-provided]. More...
 
bool netSMTPc_AcceptAuthentication (const NET_ADDR *addr)
 Accept or deny authentication requested by SMTP server. [user-provided]. More...
 

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:

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

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]eventSMTP client notification event as specified in netSMTPc_Event.
Returns
none.
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.
switch (event) {
// Email successfully sent
break;
// Timeout sending email
break;
// User authentication failed
break;
// 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]requestrequest code.
[out]bufoutput buffer to write the data to.
[in]buf_lenlength of the output buffer in bytes.
[in,out]pvarpointer 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) {
// Username to login to SMTP server
len = sprintf (buf, "guest");
break;
// Password to login to SMTP server
len = sprintf (buf, "guest");
break;
// Email address of the sender
len = sprintf (buf, "me@domain.com");
break;
// Email address of the recipient
len = sprintf (buf, "you@domain.com");
break;
// Subject of email
len = sprintf (buf, "Hello");
break;
// Email body in plain ascii format
len = sprintf (buf, "Hello, how are you?\r\n");
}
return (len);
}