SMTP client (Simple Mail Transfer Protocol) More...

#include "core/net.h"
#include "core/crypto.h"
#include "tls.h"
#include "encoding/base64.h"
#include "mac/hmac.h"
#include "hash/md5.h"

Data Structures
struct	SmtpMailAddr
	Email address. More...

struct	_SmtpClientContext
	SMTP client context. More...

Macros
#define	SMTP_CLIENT_SUPPORT ENABLED

#define	SMTP_CLIENT_MIME_SUPPORT ENABLED

#define	SMTP_CLIENT_TLS_SUPPORT DISABLED

#define	SMTP_CLIENT_LOGIN_AUTH_SUPPORT ENABLED

#define	SMTP_CLIENT_PLAIN_AUTH_SUPPORT ENABLED

#define	SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT DISABLED

#define	SMTP_CLIENT_DEFAULT_TIMEOUT 20000

#define	SMTP_CLIENT_BUFFER_SIZE 512

#define	SMTP_CLIENT_TLS_TX_BUFFER_SIZE 2048

#define	SMTP_CLIENT_TLS_RX_BUFFER_SIZE 4096

#define	SMTP_CLIENT_CONTENT_TYPE_MAX_LEN 32

#define	SMTP_CLIENT_BOUNDARY_MAX_LEN 70

#define	SMTP_CLIENT_PRIVATE_CONTEXT

#define	SMTP_RELAY_PORT 25

#define	SMTP_SUBMISSION_PORT 587

#define	SMTPS_SUBMISSION_PORT 465

#define	SMTP_REPLY_CODE_2YZ(code) ((code) >= 200 && (code) < 300)

#define	SMTP_REPLY_CODE_3YZ(code) ((code) >= 300 && (code) < 400)

#define	SMTP_REPLY_CODE_4YZ(code) ((code) >= 400 && (code) < 500)

#define	SMTP_REPLY_CODE_5YZ(code) ((code) >= 500 && (code) < 600)

#define	SmtpClientContext struct _SmtpClientContext

Typedefs
typedef error_t(*	SmtpClientReplyCallback) (SmtpClientContext context, char_t replyLine)
	Multiline reply parsing callback function. More...

typedef error_t(*	SmtpClientTlsInitCallback) (SmtpClientContext context, TlsContext tlsContext)
	TLS initialization callback function. More...

typedef error_t(*	SmtpReplyCallback) (SmtpClientContext context, char_t replyLine, uint_t replyCode)

Enumerations
enum	SmtpConnectionMode { SMTP_MODE_PLAINTEXT = 1 , SMTP_MODE_IMPLICIT_TLS = 2 , SMTP_MODE_EXPLICIT_TLS = 3 }
	SMTP connection modes. More...

enum	SmtpMailAddrType { SMTP_ADDR_TYPE_FROM = 0 , SMTP_ADDR_TYPE_TO = 1 , SMTP_ADDR_TYPE_CC = 2 , SMTP_ADDR_TYPE_BCC = 3 }
	Email address types. More...

enum	SmtpClientState { SMTP_CLIENT_STATE_DISCONNECTED = 0 , SMTP_CLIENT_STATE_CONNECTING_TCP = 1 , SMTP_CLIENT_STATE_CONNECTING_TLS = 2 , SMTP_CLIENT_STATE_CONNECTED = 3 , SMTP_CLIENT_STATE_SUB_COMMAND_1 = 4 , SMTP_CLIENT_STATE_SUB_COMMAND_2 = 5 , SMTP_CLIENT_STATE_SUB_COMMAND_3 = 6 , SMTP_CLIENT_STATE_MAIL_HEADER = 7 , SMTP_CLIENT_STATE_MAIL_BODY = 8 , SMTP_CLIENT_STATE_MULTIPART_HEADER = 9 , SMTP_CLIENT_STATE_MULTIPART_BODY = 10 , SMTP_CLIENT_STATE_DISCONNECTING = 11 }
	SMTP client states. More...

Functions
error_t	smtpClientInit (SmtpClientContext *context)
	Initialize SMTP client context. More...

error_t	smtpClientRegisterTlsInitCallback (SmtpClientContext *context, SmtpClientTlsInitCallback callback)
	Register TLS initialization callback function. More...

error_t	smtpClientSetTimeout (SmtpClientContext *context, systime_t timeout)
	Set communication timeout. More...

error_t	smtpClientBindToInterface (SmtpClientContext context, NetInterface interface)
	Bind the SMTP client to a particular network interface. More...

error_t	smtpClientConnect (SmtpClientContext context, const IpAddr serverIpAddr, uint16_t serverPort, SmtpConnectionMode mode)
	Establish a connection with the specified SMTP server. More...

error_t	smtpClientLogin (SmtpClientContext context, const char_t username, const char_t *password)
	Login to the SMTP server using the provided user name and password. More...

error_t	smtpClientSetContentType (SmtpClientContext context, const char_t contentType)
	Set the content type to be used. More...

error_t	smtpClientSetMultipartBoundary (SmtpClientContext context, const char_t boundary)
	Define the boundary string to be used (multipart encoding) More...

error_t	smtpClientWriteMailHeader (SmtpClientContext context, const SmtpMailAddr from, const SmtpMailAddr recipients, uint_t numRecipients, const char_t subject)
	Write email header. More...

error_t	smtpClientWriteMailBody (SmtpClientContext context, const void data, size_t length, size_t *written, uint_t flags)
	Write email body. More...

error_t	smtpClientWriteMultipartHeader (SmtpClientContext context, const char_t filename, const char_t contentType, const char_t contentTransferEncoding, bool_t last)
	Write multipart header. More...

error_t	smtpClientWriteMultipartBody (SmtpClientContext context, const void data, size_t length, size_t *written, uint_t flags)
	Write data to the multipart body. More...

error_t	smtpClientCloseMailBody (SmtpClientContext *context)
	Complete email sending process and wait for server's status. More...

uint_t	smtpClientGetReplyCode (SmtpClientContext *context)
	Retrieve server's reply code. More...

error_t	smtpClientDisconnect (SmtpClientContext *context)
	Gracefully disconnect from the SMTP server. More...

error_t	smtpClientClose (SmtpClientContext *context)
	Close the connection with the SMTP server. More...

void	smtpClientDeinit (SmtpClientContext *context)
	Release SMTP client context. More...

Detailed Description

SMTP client (Simple Mail Transfer Protocol)

License

SPDX-License-Identifier: GPL-2.0-or-later

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author: Oryx Embedded SARL (www.oryx-embedded.com)

Version: 2.4.0

Definition in file smtp_client.h.

Macro Definition Documentation

◆ SMTP_CLIENT_BOUNDARY_MAX_LEN

#define SMTP_CLIENT_BOUNDARY_MAX_LEN 70

Definition at line 116 of file smtp_client.h.

◆ SMTP_CLIENT_BUFFER_SIZE

#define SMTP_CLIENT_BUFFER_SIZE 512

Definition at line 88 of file smtp_client.h.

◆ SMTP_CLIENT_CONTENT_TYPE_MAX_LEN

#define SMTP_CLIENT_CONTENT_TYPE_MAX_LEN 32

Definition at line 109 of file smtp_client.h.

◆ SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT

#define SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT DISABLED

Definition at line 74 of file smtp_client.h.

◆ SMTP_CLIENT_DEFAULT_TIMEOUT

#define SMTP_CLIENT_DEFAULT_TIMEOUT 20000

Definition at line 81 of file smtp_client.h.

◆ SMTP_CLIENT_LOGIN_AUTH_SUPPORT

#define SMTP_CLIENT_LOGIN_AUTH_SUPPORT ENABLED

Definition at line 60 of file smtp_client.h.

◆ SMTP_CLIENT_MIME_SUPPORT

#define SMTP_CLIENT_MIME_SUPPORT ENABLED

Definition at line 46 of file smtp_client.h.

◆ SMTP_CLIENT_PLAIN_AUTH_SUPPORT

#define SMTP_CLIENT_PLAIN_AUTH_SUPPORT ENABLED

Definition at line 67 of file smtp_client.h.

◆ SMTP_CLIENT_PRIVATE_CONTEXT

#define SMTP_CLIENT_PRIVATE_CONTEXT

Definition at line 123 of file smtp_client.h.

◆ SMTP_CLIENT_SUPPORT

#define SMTP_CLIENT_SUPPORT ENABLED

Definition at line 39 of file smtp_client.h.

◆ SMTP_CLIENT_TLS_RX_BUFFER_SIZE

#define SMTP_CLIENT_TLS_RX_BUFFER_SIZE 4096

Definition at line 102 of file smtp_client.h.

◆ SMTP_CLIENT_TLS_SUPPORT

#define SMTP_CLIENT_TLS_SUPPORT DISABLED

Definition at line 53 of file smtp_client.h.

◆ SMTP_CLIENT_TLS_TX_BUFFER_SIZE

#define SMTP_CLIENT_TLS_TX_BUFFER_SIZE 2048

Definition at line 95 of file smtp_client.h.

◆ SMTP_RELAY_PORT

#define SMTP_RELAY_PORT 25

Definition at line 147 of file smtp_client.h.

◆ SMTP_REPLY_CODE_2YZ

#define SMTP_REPLY_CODE_2YZ ( code ) ((code) >= 200 && (code) < 300)

Definition at line 154 of file smtp_client.h.

◆ SMTP_REPLY_CODE_3YZ

#define SMTP_REPLY_CODE_3YZ ( code ) ((code) >= 300 && (code) < 400)

Definition at line 155 of file smtp_client.h.

◆ SMTP_REPLY_CODE_4YZ

#define SMTP_REPLY_CODE_4YZ ( code ) ((code) >= 400 && (code) < 500)

Definition at line 156 of file smtp_client.h.

◆ SMTP_REPLY_CODE_5YZ

#define SMTP_REPLY_CODE_5YZ ( code ) ((code) >= 500 && (code) < 600)

Definition at line 157 of file smtp_client.h.

◆ SMTP_SUBMISSION_PORT

#define SMTP_SUBMISSION_PORT 587

Definition at line 149 of file smtp_client.h.

◆ SmtpClientContext

#define SmtpClientContext struct _SmtpClientContext

Definition at line 161 of file smtp_client.h.

◆ SMTPS_SUBMISSION_PORT

#define SMTPS_SUBMISSION_PORT 465

Definition at line 151 of file smtp_client.h.

Typedef Documentation

◆ SmtpClientReplyCallback

typedef error_t(* SmtpClientReplyCallback) (SmtpClientContext *context, char_t *replyLine)

Multiline reply parsing callback function.

Definition at line 219 of file smtp_client.h.

◆ SmtpClientTlsInitCallback

typedef error_t(* SmtpClientTlsInitCallback) (SmtpClientContext *context, TlsContext *tlsContext)

TLS initialization callback function.

Definition at line 230 of file smtp_client.h.

◆ SmtpReplyCallback

typedef error_t(* SmtpReplyCallback) (SmtpClientContext *context, char_t *replyLine, uint_t replyCode)

Definition at line 285 of file smtp_client.h.

Enumeration Type Documentation

◆ SmtpClientState

enum SmtpClientState

SMTP client states.

Enumerator
SMTP_CLIENT_STATE_DISCONNECTED
SMTP_CLIENT_STATE_CONNECTING_TCP
SMTP_CLIENT_STATE_CONNECTING_TLS
SMTP_CLIENT_STATE_CONNECTED
SMTP_CLIENT_STATE_SUB_COMMAND_1
SMTP_CLIENT_STATE_SUB_COMMAND_2
SMTP_CLIENT_STATE_SUB_COMMAND_3
SMTP_CLIENT_STATE_MAIL_HEADER
SMTP_CLIENT_STATE_MAIL_BODY
SMTP_CLIENT_STATE_MULTIPART_HEADER
SMTP_CLIENT_STATE_MULTIPART_BODY
SMTP_CLIENT_STATE_DISCONNECTING

Definition at line 198 of file smtp_client.h.

◆ SmtpConnectionMode

enum SmtpConnectionMode

SMTP connection modes.

Enumerator
SMTP_MODE_PLAINTEXT
SMTP_MODE_IMPLICIT_TLS
SMTP_MODE_EXPLICIT_TLS

Definition at line 173 of file smtp_client.h.

◆ SmtpMailAddrType

enum SmtpMailAddrType

Email address types.

Enumerator
SMTP_ADDR_TYPE_FROM
SMTP_ADDR_TYPE_TO
SMTP_ADDR_TYPE_CC
SMTP_ADDR_TYPE_BCC

Definition at line 185 of file smtp_client.h.

Function Documentation

◆ smtpClientBindToInterface()

error_t smtpClientBindToInterface	(	SmtpClientContext *	context,
		NetInterface *	interface
	)

Bind the SMTP client to a particular network interface.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	interface	Network interface to be used

Returns: Error code

Definition at line 147 of file smtp_client.c.

◆ smtpClientClose()

error_t smtpClientClose ( SmtpClientContext * context )

Close the connection with the SMTP server.

Parameters

[in] context Pointer to the SMTP client context

Returns: Error code

Definition at line 1278 of file smtp_client.c.

◆ smtpClientCloseMailBody()

error_t smtpClientCloseMailBody ( SmtpClientContext * context )

Complete email sending process and wait for server's status.

Parameters

[in] context Pointer to the SMTP client context

Returns: Error code

Definition at line 1081 of file smtp_client.c.

◆ smtpClientConnect()

error_t smtpClientConnect	(	SmtpClientContext *	context,
		const IpAddr *	serverIpAddr,
		uint16_t	serverPort,
		SmtpConnectionMode	mode
	)

Establish a connection with the specified SMTP server.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	serverIpAddr	IP address of the SMTP server
[in]	serverPort	Port number
[in]	mode	SMTP connection mode

Returns: Error code

Definition at line 171 of file smtp_client.c.

◆ smtpClientDeinit()

void smtpClientDeinit ( SmtpClientContext * context )

Release SMTP client context.

Parameters

[in] context Pointer to the SMTP client context

Definition at line 1299 of file smtp_client.c.

◆ smtpClientDisconnect()

error_t smtpClientDisconnect ( SmtpClientContext * context )

Gracefully disconnect from the SMTP server.

Parameters

[in] context Pointer to the SMTP client context

Returns: Error code

Definition at line 1186 of file smtp_client.c.

◆ smtpClientGetReplyCode()

uint_t smtpClientGetReplyCode ( SmtpClientContext * context )

Retrieve server's reply code.

Parameters

[in] context Pointer to the SMTP client context

Returns: SMTP reply code

Definition at line 1159 of file smtp_client.c.

◆ smtpClientInit()

error_t smtpClientInit ( SmtpClientContext * context )

Initialize SMTP client context.

Parameters

[in] context Pointer to the SMTP client context

Returns: Error code

Definition at line 61 of file smtp_client.c.

◆ smtpClientLogin()

error_t smtpClientLogin	(	SmtpClientContext *	context,
		const char_t *	username,
		const char_t *	password
	)

Login to the SMTP server using the provided user name and password.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	username	NULL-terminated string containing the user name
[in]	password	NULL-terminated string containing the user's password

Returns: Error code

Definition at line 431 of file smtp_client.c.

◆ smtpClientRegisterTlsInitCallback()

error_t smtpClientRegisterTlsInitCallback	(	SmtpClientContext *	context,
		SmtpClientTlsInitCallback	callback
	)

Register TLS initialization callback function.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	callback	TLS initialization callback function

Returns: Error code

Definition at line 102 of file smtp_client.c.

◆ smtpClientSetContentType()

error_t smtpClientSetContentType	(	SmtpClientContext *	context,
		const char_t *	contentType
	)

Set the content type to be used.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	contentType	NULL-terminated string that holds the content type

Returns: Error code

Definition at line 484 of file smtp_client.c.

◆ smtpClientSetMultipartBoundary()

error_t smtpClientSetMultipartBoundary	(	SmtpClientContext *	context,
		const char_t *	boundary
	)

Define the boundary string to be used (multipart encoding)

Parameters

[in]	context	Pointer to the SMTP client context
[in]	boundary	NULL-terminated string that holds the boundary string

Returns: Error code

Definition at line 520 of file smtp_client.c.

◆ smtpClientSetTimeout()

error_t smtpClientSetTimeout	(	SmtpClientContext *	context,
		systime_t	timeout
	)

Set communication timeout.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	timeout	Timeout value, in milliseconds

Returns: Error code

Definition at line 126 of file smtp_client.c.

◆ smtpClientWriteMailBody()

error_t smtpClientWriteMailBody	(	SmtpClientContext *	context,
		const void *	data,
		size_t	length,
		size_t *	written,
		uint_t	flags
	)

Write email body.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	data	Pointer to a buffer containing the data to be written
[in]	length	Number of data bytes to write
[in]	written	Number of bytes that have been written (optional parameter)
[in]	flags	Set of flags that influences the behavior of this function

Returns: Error code

Definition at line 727 of file smtp_client.c.

◆ smtpClientWriteMailHeader()

error_t smtpClientWriteMailHeader	(	SmtpClientContext *	context,
		const SmtpMailAddr *	from,
		const SmtpMailAddr *	recipients,
		uint_t	numRecipients,
		const char_t *	subject
	)

Write email header.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	from	Email address of the sender
[in]	recipients	Email addresses of the recipients
[in]	numRecipients	Number of email addresses in the list
[in]	subject	NULL-terminated string containing the email subject

Returns: Error code

Definition at line 559 of file smtp_client.c.

◆ smtpClientWriteMultipartBody()

error_t smtpClientWriteMultipartBody	(	SmtpClientContext *	context,
		const void *	data,
		size_t	length,
		size_t *	written,
		uint_t	flags
	)

Write data to the multipart body.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	data	Pointer to the buffer containing the data to be transmitted
[in]	length	Number of data bytes to send
[out]	written	Actual number of bytes written (optional parameter)
[in]	flags	Set of flags that influences the behavior of this function

Returns: Error code

Definition at line 934 of file smtp_client.c.

◆ smtpClientWriteMultipartHeader()

error_t smtpClientWriteMultipartHeader	(	SmtpClientContext *	context,
		const char_t *	filename,
		const char_t *	contentType,
		const char_t *	contentTransferEncoding,
		bool_t	last
	)

Write multipart header.

Parameters

[in]	context	Pointer to the SMTP client context
[in]	filename	NULL-terminated string that holds the file name (optional parameter)
[in]	contentType	NULL-terminated string that holds the content type (optional parameter)
[in]	contentTransferEncoding	NULL-terminated string that holds the content transfer encoding (optional parameter)
[in]	last	This flag indicates whether the multipart header is the final one

Returns: Error code

Definition at line 797 of file smtp_client.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

License

Macro Definition Documentation

◆ SMTP_CLIENT_BOUNDARY_MAX_LEN

◆ SMTP_CLIENT_BUFFER_SIZE

◆ SMTP_CLIENT_CONTENT_TYPE_MAX_LEN

◆ SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT

◆ SMTP_CLIENT_DEFAULT_TIMEOUT

◆ SMTP_CLIENT_LOGIN_AUTH_SUPPORT

◆ SMTP_CLIENT_MIME_SUPPORT

◆ SMTP_CLIENT_PLAIN_AUTH_SUPPORT

◆ SMTP_CLIENT_PRIVATE_CONTEXT

◆ SMTP_CLIENT_SUPPORT

◆ SMTP_CLIENT_TLS_RX_BUFFER_SIZE

◆ SMTP_CLIENT_TLS_SUPPORT

◆ SMTP_CLIENT_TLS_TX_BUFFER_SIZE

◆ SMTP_RELAY_PORT

◆ SMTP_REPLY_CODE_2YZ

◆ SMTP_REPLY_CODE_3YZ

◆ SMTP_REPLY_CODE_4YZ

◆ SMTP_REPLY_CODE_5YZ

◆ SMTP_SUBMISSION_PORT

◆ SmtpClientContext

◆ SMTPS_SUBMISSION_PORT

Typedef Documentation

◆ SmtpClientReplyCallback

◆ SmtpClientTlsInitCallback

◆ SmtpReplyCallback

Enumeration Type Documentation

◆ SmtpClientState

◆ SmtpConnectionMode

◆ SmtpMailAddrType

Function Documentation

◆ smtpClientBindToInterface()

◆ smtpClientClose()

◆ smtpClientCloseMailBody()

◆ smtpClientConnect()

◆ smtpClientDeinit()

◆ smtpClientDisconnect()

◆ smtpClientGetReplyCode()

◆ smtpClientInit()

◆ smtpClientLogin()

◆ smtpClientRegisterTlsInitCallback()

◆ smtpClientSetContentType()

◆ smtpClientSetMultipartBoundary()

◆ smtpClientSetTimeout()

◆ smtpClientWriteMailBody()

◆ smtpClientWriteMailHeader()

◆ smtpClientWriteMultipartBody()

◆ smtpClientWriteMultipartHeader()