Detailed Description

A minimal secure SMTP client library (SMTPS and STARTTLS).

The SMTP library is delivered as an example program. The library uses the socket functions in selib.c for secure and non-secure communication.

A Visual C++ project is provided in build/VC-Win/examples.sln. This project enables you to quickly test the library on a Windows computer.

Modify one of the two example files: example.c or example.cpp. The example.cpp source code file uses the C++ wrapper API, thus simplifying the use of the library.

Data Structures
struct	SMTP
	This class is a minimal SMTP client that takes an email message body and passes it on to a SMTP server. More...

Macros
#define	SMTP_getEcode(o) (o)->eCode
	Documentation: SMTP::getEcode. More...

#define	SMTP_setContentType(o, type) (o)->contentType=type
	Documentation: SMTP::setContentType. More...

#define	SMTP_bit8(o) (o)->eightBit
	Returns true if server supports 8BITMIME. More...

Typedefs
typedef struct SMTP	SMTP
	This class is a minimal SMTP client that takes an email message body and passes it on to a SMTP server. More...

Enumerations
enum	SMTP_ErrCode { SMTP_NoError =0 , SMTP_DataCommitted , SMTP_ErrHostName , SMTP_ErrSocketCreate , SMTP_ErrConnect , SMTP_ErrHELO , SMTP_ErrMAILFROM , SMTP_ErrDATA , SMTP_ErrRCPTTO , SMTP_ErrSocketClosed , SMTP_ErrSmtpResponseCode , SMTP_ErrWriteStarted , SMTP_ErrNoAuthSup , SMTP_ErrAuth , SMTP_ErrSslCon , SMTP_ErrCertNotTrusted }
	SMTP error codes. More...

Functions
void	SMTP_constructor (SMTP o, const char from, const char to, const char subject, const char smtpServer, int port, SharkSsl sharkSsl, int startTLS, const char username, const char password, const char clientDomainName, const char serverDomainName, SeCtx *ctx)
	Documentation: SMTP::SMTP. More...

void	SMTP_destructor (SMTP *o)
	Documentation: SMTP::~SMTP. More...

int	SMTP_addRecipient (SMTP o, const char to)
	Documentation: SMTP::addRecipient. More...

int	SMTP_write (SMTP o, const char txt, int len)
	Documentation: SMTP::write. More...

int	SMTP_printf (SMTP o, const char fmt,...)
	Documentation: SMTP::printf. More...

int	SMTP_vprintf (SMTP o, const char fmt, va_list argList)
	Documentation: SMTP::vprintf. More...

int	SMTP_commit (SMTP *o)
	Documentation: SMTP::commit. More...

const char *	SMTP_getEmsg (SMTP *o)
	Returns the SMTP error message if any. More...

	SMTP::SMTP (const char from, const char to, const char subject, const char smtpServer, int port=25, SharkSsl sharkSsl=0, bool startTLS=false, const char username=0, const char password=0, const char clientDomainName=0, const char serverDomainName=0, SeCtx ctx=0)
	Initiate the SMTP email message. More...

	SMTP::~SMTP ()
	The destructor automatically commits the email if you do not call SMTP::commit. More...

int	SMTP::addRecipient (const char *to)
	Optionally add more recipients to this email. More...

void	SMTP::setContentType (const char *type)
	Set content-type. More...

int	SMTP::write (const char *txt, int len=-1)
	Add body text to email. More...

int	SMTP::printf (const char *fmt,...)
	Add body text to email. More...

const char *	SMTP::getEmsg ()
	Returns the SMTP error message if any. More...

int	SMTP::commit ()
	Commit (send) email. More...

Macro Definition Documentation

◆ SMTP_bit8

#define SMTP_bit8 ( o ) (o)->eightBit

Returns true if server supports 8BITMIME.

◆ SMTP_getEcode

#define SMTP_getEcode ( o ) (o)->eCode

Documentation: SMTP::getEcode.

◆ SMTP_setContentType

#define SMTP_setContentType	(	o,
		type
	)	(o)->contentType=type

Documentation: SMTP::setContentType.

Typedef Documentation

◆ SMTP

typedef struct SMTP SMTP

This class is a minimal SMTP client that takes an email message body and passes it on to a SMTP server.

Email messages can be used to provide status reports or alarm notifications for embedded devices.

This ANSI C library, is designed as one class with C++ wrapper functions in the header file. Please refer to the following article for more information on Object Oriented programming in C code .

C++ Example code:

SMTP smtp("device1@realtimelogic.com", //const char* from,
          "alarmcentral@realtimelogic.com", //const char* to,
          "Alarm from device 1", //const char* subject,
          "smtp.mandrillapp.com", //const char* smtpServer,
          587, //int port,
          &sharkSsl,
          TRUE, //int startTLS,
          "device1@realtimelogic.com", //const char* username,
          "mandrill-key", //const char* password
          0, //const char* clientDomainName,
          "smtp.mandrillapp.com"); //const char* serverDomainName
if(smtp.getEcode() == SMTP_NoError)
   if( !smtp.addRecipient("ginfo@realtimelogic.com") )
      if( ! smtp.printf("This email was sent at %d\n", time(0)) )
         if( !smtp.commit() )
            return; //Success.
 
SMTP_ErrCode eCode = smtp.getEcode();
// Handle error.

Enumeration Type Documentation

◆ SMTP_ErrCode

enum SMTP_ErrCode

SMTP error codes.

Enumerator
SMTP_NoError	OK.
SMTP_DataCommitted	Not an error code: means that the library has started sending data.
SMTP_ErrHostName	Hostname does not resolve or the client is unable to connect to server.
SMTP_ErrSocketCreate	Cannot create socket.
SMTP_ErrConnect	Cannot connect.
SMTP_ErrHELO	EHLO (Extended SMTP (ESMTP)) required, but not supported by server.
SMTP_ErrMAILFROM	Failed sending MAIL FROM:<s> BODY=8BITMIME.
SMTP_ErrDATA	Failed sending the initial DATA message.
SMTP_ErrRCPTTO	Failed sending RCPT TO:<s>
SMTP_ErrSocketClosed	Socket unexpectedly closed.
SMTP_ErrSmtpResponseCode	Cannot decode response data.
SMTP_ErrWriteStarted	Cannot add recipients after data is committed: see SMTP_DataCommitted.
SMTP_ErrNoAuthSup	Unknown/unsupported server authentication request.
SMTP_ErrAuth	Server requires credentials, but no credentials were provided.
SMTP_ErrSslCon	SharkSsl_createCon failed.
SMTP_ErrCertNotTrusted	Server certificate not trusted. Disable by setting serverDomainName to NULL when calling SMTP::SMTP.

Function Documentation

◆ addRecipient()

int SMTP::addRecipient ( const char * to )

Optionally add more recipients to this email.

This function cannot be called after you call SMTP::write or SMTP::printf.

See also: SMTP_addRecipient

Parameters

to	const char *; required NUL-terminated additional recipient, borrowed for this call. Call before the body starts.

Returns: int: 0 if accepted; -1 on invalid state or SMTP/socket failure.

◆ commit()

int SMTP::commit ( )

Commit (send) email.

See also: SMTP_commit

Returns: int: 0 when submission succeeds without a stored error; -1 on final I/O failure or a stored SMTP_ErrCode value otherwise. Check any nonzero result and getEcode. The socket and owned TLS connection are closed/released even on failure.

◆ getEmsg()

const char * SMTP::getEmsg ( )

Returns the SMTP error message if any.

Returns: const char *; borrowed current response/error text, or NULL when the response buffer is empty. Valid only until the next operation modifies the buffer or the instance is destroyed.

◆ printf()

int SMTP::printf	(	const char *	fmt,
			...
	)

Add body text to email.

See also: SMTP_printf

Parameters

fmt	const char *; required NUL-terminated BufPrint format string, borrowed for this call.
...	Values matching the format conversions; string arguments remain valid for this call.

Returns: int: nonnegative formatted character count on success; negative on formatting/output failure. Unlike write, success can be positive.

◆ setContentType()

void SMTP::setContentType ( const char * type )

Set content-type.

Parameters

type	the content type defaults to "text/plain; charset=utf-8".

See also: SMTP_setContentType

◆ SMTP()

SMTP::SMTP	(	const char *	from,
		const char *	to,
		const char *	subject,
		const char *	smtpServer,
		int	port = `25`,
		SharkSsl *	sharkSsl = `0`,
		bool	startTLS = `false`,
		const char *	username = `0`,
		const char *	password = `0`,
		const char *	clientDomainName = `0`,
		const char *	serverDomainName = `0`,
		SeCtx *	ctx = `0`
	)

Initiate the SMTP email message.

Parameters

from	the sender of the email.
to	the receiver of this email.
subject	email message subject.
smtpServer	The name or IP address of the SMTP server.
port	the SMTP server port number. Default is 25.
sharkSsl	use secure connection, either SMTPS or STARTTLS.
startTLS	use STARTTLS (RFC 3207) if TRUE, otherwise, use SMTPS.
username	the username is required by SMTP servers requiring AUTH.
password	the password is required by SMTP servers requiring AUTH.
clientDomainName	defaults to "localhost" if not set.
serverDomainName	must be set to the expected server's SSL certificate domain name. The SMTP library will not do any server certificate validation if this variable is set to NULL.
ctx	for bare metal systems

See also: SMTP_constructor

◆ SMTP_addRecipient()

int SMTP_addRecipient	(	SMTP *	o,
		const char *	to
	)

Documentation: SMTP::addRecipient.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.
to	const char *; required NUL-terminated additional recipient, borrowed for this call. Call before the body starts.

Returns: int: 0 if accepted; -1 on invalid state or SMTP/socket failure.

◆ SMTP_commit()

int SMTP_commit ( SMTP * o )

Documentation: SMTP::commit.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.

Returns: int: 0 when submission succeeds without a stored error; -1 on final I/O failure or a stored SMTP_ErrCode value otherwise. Check any nonzero result and getEcode. The socket and owned TLS connection are closed/released even on failure.

◆ SMTP_constructor()

void SMTP_constructor	(	SMTP *	o,
		const char *	from,
		const char *	to,
		const char *	subject,
		const char *	smtpServer,
		int	port,
		SharkSsl *	sharkSsl,
		int	startTLS,
		const char *	username,
		const char *	password,
		const char *	clientDomainName,
		const char *	serverDomainName,
		SeCtx *	ctx
	)

Documentation: SMTP::SMTP.

The constructor connects and may authenticate.

It has no return value: inspect SMTP_getEcode before using the object. The instance owns its socket and any connection created from sharkSsl.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.
from	const char *; required sender address, retained until message submission.
to	const char *; required initial recipient address, retained until message submission.
subject	const char *; required NUL-terminated subject, retained until message submission.
smtpServer	const char *; required NUL-terminated connection hostname/address, borrowed during construction.
port	int; remote TCP port from 1 to 65535.
sharkSsl	SharkSsl *; client TLS factory, or NULL for unencrypted SMTP. Keep it alive until commit/destruction releases the connection.
startTLS	int; nonzero selects STARTTLS; zero selects immediate TLS when sharkSsl is supplied.
username	const char *; optional NUL-terminated authentication username, borrowed during construction.
password	const char *; required with username; NUL-terminated authentication password, borrowed during construction.
clientDomainName	const char *; retained NUL-terminated EHLO domain, or NULL for localhost.
serverDomainName	const char *; retained expected TLS certificate name. NULL skips the expected-name/trust check in this example; provide it for authenticated TLS.
ctx	SeCtx *; retained socket-stack context on bare-metal ports, or NULL on ports that do not use it.

◆ SMTP_destructor()

void SMTP_destructor ( SMTP * o )

Documentation: SMTP::~SMTP.

Calls SMTP_commit and releases the connection.

This can submit buffered mail and perform network I/O; it is not a discard operation. It does not free the caller-owned SMTP storage.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.

◆ SMTP_getEmsg()

const char * SMTP_getEmsg ( SMTP * o )

Returns the SMTP error message if any.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.

Returns: const char *; borrowed current response/error text, or NULL when the response buffer is empty. Valid only until the next operation modifies the buffer or the instance is destroyed.

◆ SMTP_printf()

int SMTP_printf	(	SMTP *	o,
		const char *	fmt,
			...
	)

Documentation: SMTP::printf.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.
fmt	const char *; required NUL-terminated BufPrint format string, borrowed for this call.
...	Values matching the format conversions; string arguments remain valid for this call.

Returns: int: nonnegative formatted character count on success; negative on formatting/output failure. Unlike write, success can be positive.

◆ SMTP_vprintf()

int SMTP_vprintf	(	SMTP *	o,
		const char *	fmt,
		va_list	argList
	)

Documentation: SMTP::vprintf.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.
fmt	const char *; required NUL-terminated BufPrint format string.
argList	va_list; initialized argument list matching fmt. The caller remains responsible for va_end; make a va_copy before reuse.

Returns: int: nonnegative formatted character count on success; negative on formatting/output failure.

◆ SMTP_write()

int SMTP_write	(	SMTP *	o,
		const char *	txt,
		int	len
	)

Documentation: SMTP::write.

Parameters

o	SMTP *; required initialized instance, owned by the caller. Calls can block on the network.
txt	const char *; body bytes borrowed for this call, required for nonempty data.
len	int; byte count, or a negative value to use strlen(txt), which requires a NUL-terminated string.

Returns: int: 0 when buffered/written successfully; -1 on failure. Success does not yet confirm delivery: finish with commit.

◆ write()

int SMTP::write	(	const char *	txt,
		int	len = `-1`
	)

Add body text to email.

See also: SMTP_write

Parameters

txt	const char *; body bytes borrowed for this call, required for nonempty data.
len	int; byte count, or a negative value to use strlen(txt), which requires a NUL-terminated string.

Returns: int: 0 when buffered/written successfully; -1 on failure. Success does not yet confirm delivery: finish with commit.

◆ ~SMTP()

SMTP::~SMTP ( )

The destructor automatically commits the email if you do not call SMTP::commit.

See also: SMTP_destructor

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ SMTP_bit8

◆ SMTP_getEcode

◆ SMTP_setContentType

Typedef Documentation

◆ SMTP

Enumeration Type Documentation

◆ SMTP_ErrCode

Function Documentation

◆ addRecipient()

◆ commit()

◆ getEmsg()

◆ printf()

◆ setContentType()

◆ SMTP()

◆ SMTP_addRecipient()

◆ SMTP_commit()

◆ SMTP_constructor()

◆ SMTP_destructor()

◆ SMTP_getEmsg()

◆ SMTP_printf()

◆ SMTP_vprintf()

◆ SMTP_write()

◆ write()

◆ ~SMTP()