Simple Mail Transfer Protocol

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.
#define	SMTP_setContentType(o, type)   (o)->contentType=type
	Documentation: SMTP::setContentType.
#define	SMTP_bit8(o)   (o)->eightBit
	Returns true if server supports 8BITMIME.

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.
void	SMTP_destructor (SMTP *o)
	Documentation: SMTP::~SMTP.
int	SMTP_addRecipient (SMTP *o, const char *to)
	Documentation: SMTP::addRecipient.
int	SMTP_write (SMTP *o, const char *txt, int len)
	Documentation: SMTP::write.
int	SMTP_printf (SMTP *o, const char *fmt,...)
	Documentation: SMTP::printf.
int	SMTP_vprintf (SMTP *o, const char *fmt, va_list argList)
	Documentation: SMTP::vprintf.
int	SMTP_commit (SMTP *o)
	Documentation: SMTP::commit.
const char *	SMTP_getEmsg (SMTP *o)
	Returns the SMTP error message if any.
	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.
int	SMTP::commit ()
	Commit (send) email. More...

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

commit()

int SMTP::commit

(

)

Commit (send) email.

See also

SMTP_commit

printf()

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

Add body text to email.

See also

SMTP_printf

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

write()

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

Add body text to email.

See also

SMTP_write

~SMTP()

SMTP::~SMTP

(

)

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

See also

SMTP_destructor