SharkSSL™ Embedded SSL/TLS Stack
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

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
typethe 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
fromthe sender of the email.
tothe receiver of this email.
subjectemail message subject.
smtpServerThe name or IP address of the SMTP server.
portthe SMTP server port number. Default is 25.
sharkSsluse secure connection, either SMTPS or STARTTLS.
startTLSuse STARTTLS (RFC 3207) if TRUE, otherwise, use SMTPS.
usernamethe username is required by SMTP servers requiring AUTH.
passwordthe password is required by SMTP servers requiring AUTH.
clientDomainNamedefaults to "localhost" if not set.
serverDomainNamemust 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.
ctxfor 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
SMTP_ErrCode
SMTP_ErrCode
SMTP error codes.
Definition: SMTP.h:63
SMTP
This class is a minimal SMTP client that takes an email message body and passes it on to a SMTP serve...
Definition: SMTP.h:170
SMTP_NoError
@ SMTP_NoError
OK.
Definition: SMTP.h:66