smtp_client.h File Reference

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"

Go to the source code of this file.

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_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 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

Copyright (C) 2010-2019 Oryx Embedded SARL. All rights reserved.

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
1.9.6

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_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 142 of file smtp_client.h.

◆ SMTP_REPLY_CODE_2YZ

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

Definition at line 149 of file smtp_client.h.

◆ SMTP_REPLY_CODE_3YZ

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

Definition at line 150 of file smtp_client.h.

◆ SMTP_REPLY_CODE_4YZ

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

Definition at line 151 of file smtp_client.h.

◆ SMTP_REPLY_CODE_5YZ

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

Definition at line 152 of file smtp_client.h.

◆ SMTP_SUBMISSION_PORT

#define SMTP_SUBMISSION_PORT   587

Definition at line 144 of file smtp_client.h.

◆ SmtpClientContext

#define SmtpClientContext   struct _SmtpClientContext

Definition at line 156 of file smtp_client.h.

◆ SMTPS_SUBMISSION_PORT

#define SMTPS_SUBMISSION_PORT   465

Definition at line 146 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 214 of file smtp_client.h.

◆ SmtpClientTlsInitCallback

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

TLS initialization callback function.

Definition at line 225 of file smtp_client.h.

◆ SmtpReplyCallback

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

Definition at line 279 of file smtp_client.h.

Enumeration Type Documentation

◆ 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 193 of file smtp_client.h.

◆ SmtpConnectionMode

SMTP connection modes.

Enumerator
SMTP_MODE_PLAINTEXT 
SMTP_MODE_IMPLICIT_TLS 
SMTP_MODE_EXPLICIT_TLS 

Definition at line 168 of file smtp_client.h.

◆ SmtpMailAddrType

Email address types.

Enumerator
SMTP_ADDR_TYPE_FROM 
SMTP_ADDR_TYPE_TO 
SMTP_ADDR_TYPE_CC 
SMTP_ADDR_TYPE_BCC 

Definition at line 180 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]contextPointer to the SMTP client context
[in]interfaceNetwork 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]contextPointer 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]contextPointer 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]contextPointer to the SMTP client context
[in]serverIpAddrIP address of the SMTP server
[in]serverPortPort number
[in]modeSMTP 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]contextPointer 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]contextPointer 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]contextPointer 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]contextPointer 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]contextPointer to the SMTP client context
[in]usernameNULL-terminated string containing the user name
[in]passwordNULL-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]contextPointer to the SMTP client context
[in]callbackTLS 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]contextPointer to the SMTP client context
[in]contentTypeNULL-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]contextPointer to the SMTP client context
[in]boundaryNULL-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]contextPointer to the SMTP client context
[in]timeoutTimeout 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]contextPointer to the SMTP client context
[in]dataPointer to a buffer containing the data to be written
[in]lengthNumber of data bytes to write
[in]writtenNumber of bytes that have been written (optional parameter)
[in]flagsSet 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]contextPointer to the SMTP client context
[in]fromEmail address of the sender
[in]recipientsEmail addresses of the recipients
[in]numRecipientsNumber of email addresses in the list
[in]subjectNULL-terminsated 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 the multipart body.

Parameters
[in]contextPointer to the SMTP client context
[in]dataPointer to the buffer containing the data to be transmitted
[in]lengthNumber of data bytes to send
[out]writtenActual number of bytes written (optional parameter)
[in]flagsSet 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]contextPointer to the SMTP client context
[in]filenameNULL-terminated string that holds the file name (optional parameter)
[in]contentTypeNULL-terminated string that holds the content type (optional parameter)
[in]contentTransferEncodingNULL-terminated string that holds the content transfer encoding (optional parameter)
[in]lastThis flag indicates whether the multipart header is the final one
Returns
Error code

Definition at line 797 of file smtp_client.c.