SMTP Client API#

SMTPc_ConfigureMemSeg()#

Description#

Configure the memory segment that will be used to allocate internal data needed by SMTP client module instead of the default memory segment.

Files#

smtp_client.h/smtp_client.c

Prototype#

void  SMTPc_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

Arguments#

p_mem_seg

Pointer to the memory segment from which the internal data will be allocated. If DEF_NULL, the internal data will be allocated from the global Heap.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before SMTPc_Init(). If it is not called, default values will be used to initialize the module.

SMTPc_ConfigureAuthBufLen()#

Description#

Configure the size of internal authentication input buffer.

Files#

smtp_client.h/smtp_client.c

Prototype#

void  SMTPc_ConfigureAuthBufLen (CPU_INT16U  buf_len)

Arguments#

buf_len

Input buffer length to configure.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before SMTPc_Init(). If it is not called, default values will be used to initialize the module.

  2. The maximum input buffer passed to the base 64 encoder depends of the configured maximum lengths for the username and password. Two additional characters are added to these values to account for the delimiter.

  3. The size of the output buffer the base 64 encoder produces is typically bigger than the input buffer by a factor of (4 x 3). However, when padding is necessary, up to 3 additional characters could by appended. Finally, one more character is used to NULL terminate the buffer.

SMTPc_Init()#

Description#

Initialize the SMTP client module.

Files#

smtp_client.h/smtp_client.c

Prototype#

void  SMTPc_Init (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

None.

SMTPc_DfltCfgSet()#

Description#

Sets the Default Configuration that will be used for opening TCP connections inside the SMTP client module.

Files#

smtp_client.h/smtp_client.c

Prototype#

void SMTPc_DfltCfgSet (CPU_INT16U  timeout_conn_ms,
                       CPU_INT16U  timeout_rx_ms,
                       CPU_INT16U  timeout_tx_ms,
                       CPU_INT16U  timeout_close_ms,
                       RTOS_ERR   *p_err)

Arguments#

timeout_conn_ms

Timeout on connection request.

timeout_rx_ms

Timeout on receive.

timeout_tx_ms

Timeout on transmit.

timeout_close_ms

Timeout on socket close

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

  1. The new configuration value are applied only on new connection.

SMTPc_MsgAlloc()#

Description#

Get a message structure.

Files#

smtp_client.h/smtp_client.c

Prototype#

SMTPc_MSG  *SMTPc_MsgAlloc (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

Pointer to an allocated message structure.

Notes / Warnings#

  1. If the message structure is allocated from the application. The function SMTPc_MsgClr() must be called to free internal structure allocated during message processing.

SMTPc_MsgFree()#

Description#

Free a message structure.

Files#

smtp_client.h/smtp_client.c

Prototype#

void SMTPc_MsgFree (SMTPc_MSG *p_msg,
                    RTOS_ERR *p_err)

Arguments#

p_msg

Pointer to the message structure to free.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

None.

SMTPc_MsgClr()#

Description#

Clear a message structure to be reused for another message.

Files#

smtp_client.h/smtp_client.c

Prototype#

void SMTPc_MsgClr (SMTPc_MSG *p_msg,
                   RTOS_ERR  *p_err)

Arguments#

p_msg

Pointer to the message structure to clear.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

  1. If the message structure is allocated from the application. The function SMTPc_MsgClr() must be called to free internal structure allocated during message processing.

SMTPc_MsgSetParam()#

Description#

Configure message parameter.

Files#

smtp_client.h/smtp_client.c

Prototype#

void SMTPc_MsgSetParam (SMTPc_MSG        *p_msg,
                        SMTPc_MSG_PARAM   param_type,
                        void             *p_val,
                        RTOS_ERR         *p_err)

Arguments#

p_msg

Pointer to the message structure to configure.

param_type

Parameter to set in the message:

  • SMTPc_FROM_ADDR

  • SMTPc_FROM_DISPL_NAME

  • SMTPc_TO_ADDR

  • SMTPc_CC_ADDR

  • SMTPc_BCC_ADDR

  • SMTPc_REPLY_TO_ADDR

  • SMTPc_SENDER_ADDR

  • SMTPc_ATTACHMENT

  • SMTPc_MSG_SUBJECT

  • SMTPc_MSG_BODY

p_val

Pointer to the parameter value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

None.

SMTPc_SendMail()#

Description#

Sends an email.

Files#

smtp_client.h/smtp_client.c

Prototype#

void  SMTPc_SendMail (CPU_CHAR                *p_host_name,
                      CPU_INT16U               port,
                      CPU_CHAR                *p_username,
                      CPU_CHAR                *p_pwd,
                      NET_APP_SOCK_SECURE_CFG *p_secure_cfg,
                      SMTPc_MSG               *p_msg,
                      RTOS_ERR                *p_err)

Arguments#

p_host_name

Pointer to host name of the SMTP server to contact. Can be also an IP address.

port

TCP port to use, or '0' if SMTPc_DFLT_PORT.

p_username

Pointer to user name, if authentication enabled.

p_pwd

Pointer to password, if authentication enabled.

p_secure_cfg

Pointer to the secure configuration (TLS/SSL):

  • DEF_NULL, if no security enabled.

  • Pointer to a structure that contains the parameters.

p_msg

SMTPc_MSG structure encapsulating the message to send.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

  1. The function SMTPc_MsgSetParam() must be called before it can send a message.

SMTPc_Connect()#

Description#

Establishes a TCP connection to the SMTP server and initiates the SMTP session.

Files#

smtp_client.h/smtp_client.c

Prototype#

NET_SOCK_ID  SMTPc_Connect (CPU_CHAR                 *p_host_name,
                            CPU_INT16U                port,
                            CPU_CHAR                 *p_username,
                            CPU_CHAR                 *p_pwd,
                            NET_APP_SOCK_SECURE_CFG  *p_secure_cfg,
                            RTOS_ERR                 *p_err)

Arguments#

p_host_name

Pointer to hostname of the SMTP server to contact (can be an IP address).

port

TCP port to use, or enter '0' if SMTPc_DFLT_PORT.

p_username

Pointer to user name, if authentication is enabled.

p_pwd

Pointer to password, if authentication is enabled.

p_secure_cfg

Pointer to the secure configuration (TLS/SSL):

  • DEF_NULL, if no security is enabled.

  • Pointer to a structure that contains the parameters.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

  • Socket descriptor/handle identifier, if NO error.

  • -1, otherwise.

Notes / Warnings#

  1. Network security manager MUST be available and enabled to initialize the server in secure mode.

  2. If anything goes wrong while trying to connect to the server, the socket is closed by calling NetSock_Close. In case of a failure to establish the TCP connection, all data structures are returned to their original state.

    If the failure occurs when initiating the session, the application is responsible to take the appropriate action(s).

  3. If authentication is disabled (SMTPc_CFG_AUTH_EN set to DEF_ENABLED), the 'p_username' and 'p_pwd' parameters should be passed as a NULL pointer.

  4. The server will send a 220 "Service ready" reply when the connection is completed. The SMTP protocol allows a server to formally reject a transaction, while still allowing the initial connection by responding with a 554 "Transaction failed" reply.

  5. The Plain-text (PLAIN) authentication mechanism is implemented here. However, it takes some liberties from RFC #4964, section 4 'The AUTH Command', stating the "A server implementation MUST implement a configuration in which it does not permit any plaintext password mechanisms, unless either the STARTTLS command has been negotiated or some other mechanism that protects the session from password snooping has been provided".

    Since this client does not support SSL or TLS, nor any other protection against password snooping, it relies on the server to NOT fully follow RFC #4954 to be successful.

SMTPc_Disconnect()#

Description#

Closes the connection between the client and the server.

Files#

smtp_client.h/smtp_client.c

Prototype#

void  SMTPc_Disconnect (NET_SOCK_ID   sock_id,
                        RTOS_ERR     *p_err)

Arguments#

sock_id

Socket ID.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

  1. The receiver (client) MUST NOT intentionally close the transmission channel until it receives and replies to a QUIT command.

  2. The receiver of the QUIT command MUST send an OK reply, then close the transmission channel.

SMTPc_SendMsg()#

Description#

Sends a message (an instance of the SMTPc_MSG structure) to the SMTP server.

Files#

smtp_client.h/smtp_client.c

Prototype#

void  SMTPc_SendMsg (NET_SOCK_ID   sock_id,
                     SMTPc_MSG    *p_msg,
                     RTOS_ERR     *p_err)

Arguments#

sock_id

Socket ID.

p_msg

SMTPc_MSG structure encapsulating the message to send.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

  1. The function SMTPc_SetMsg must be called before it can send a message.

  2. The message must have at least one receiver: either "To", "CC", or "BCC".