SFXSMTPSender

Class for sending a SMTP mail.

#include <SFXSMTPSender.h.hpp>

class SFXSMTPSender;

SFMTYPEDEFCLASS(SFXSMTPSender)

Collaboration diagram.

Description

Procedure to send a SMTP mail

Create the instance of the SFXSMTPSender class.
Create the instance of the SFXMailMessage class, i.e. mail message.
Set the IP address and port number of the SMTP server using the SFXSMTPSender::SetServer function.
Register the created mail message and the callback function using the SFXSMTPSender::SendMessage function. And then call the SFXSMTPSender::SendMessage function to start sending the mail.

Example 485. The method to send a mail using the SFXSMTPSender class

class MyClass {
private:
    SFXSMTPSender _sender;
    CALLBACK_DECLARE_SFXSMTPSENDER(SMTPCallback)
public:
    Void Start(Void);
};

Void MyClass::Start(Void)
{
    SFCError error;
    SFXMailMessage message;

    // set From field to mail header
    message.SetFromField("fromaddress@example.com");

    // add To addresses to mail header
    message.AddToField("toaddress1@example.com");
    message.AddToField("toaddress2@example.com");

    // set Subject field to mail header
    message.SetSubjectField("Mail Subject");

    // set Body of the mail message
    message.SetBody("Mail test\r\nThis mail is sent by SFXSMTPSender.\r\n");

    // set IP address and port number of SMTP server (domain is automatically resolved)
    _sender.SetServer(SFXSocketAddress("smtpserver.example.com:25"));

    // register SMTPCallback as callback function, and then send mail
    // SMTPCallback function will be notified of completion of sending mail
    if ((error = _sender.SendMessage(&message,
        CALLBACK_FUNCTION(SMTPCallback))) != SFERR_NO_ERROR) {
        // callback will never be notifiled to SMTPCallback function if error is not SFERR_NO_ERROR
        // error handling for this case
        .....
    }
}

// callback function notified of completion of sending mail
CALLBACK_IMPLEMENT_SFXSMTPSENDER(MyClass, SMTPCallback, error)
{
    if (error == SFERR_NO_ERROR) {
        // succeed to send mail
        TRACE("Mail is sent.");
    }
    else {
        TRACE("Failed to send mail: %d", error);
    }
}

The SFXMailMessage class instance should set the From field and the To field. The Cc and Bcc fileds can be set if neccessary.

The mail can be sent by SFXSMTPSender::SendText function without using SFXMailMessage class. In this case, the mail text must be created from the mail header and mail body. The sender's host name, the sender's mail address, and the recipient's mail address are included in the mail header.

Reference

SFXSMTP | Mail Sending

Member

Constructor/Destructor
SFXSMTPSender( `Void` ) Constructor of SFXSMTPSender class.
~SFXSMTPSender( `Void` ) Destructor of SFXSMTPSender class.

Public Functions
`SFCError`	AddTo( `SFXAnsiStringConstRef` to ) Add the mail address of recipient.
`Void`	Cancel( `Void` ) Cancel sending a SMTP mail.
`Void`	ClearTo( `Void` ) Delete all the mail addresses of recipients.
`ProgressEnum`	GetProgress( `Void` ) Get the progress status of sending a SMTP mail.
`SFXSMTPRef`	GetSFXSMTP( `Void` ) Get the instance of the SFXSMTP class that is internally used.
`Bool`	GetSSLMode( `Void` ) Get the SSL connection mode.
`UInt32`	GetTrustMode( `Void` ) Get the SSL trust mode.
`Bool`	IsQuit( `Void` ) Check whether the QUIT command has been sent or not.
`SFCError`	SendMessage( `SFXMailMessagePtr` message , `CallbackSPP` spp , `VoidPtr` reference ) Send the mail message.
`SFCError`	SendText( `SFXAnsiStringConstRef` text , `CallbackSPP` spp , `VoidPtr` reference ) Send the mail text.
`SFCError`	SetAuthorization( `AuthEnum` auth , `SFXAnsiStringConstRef` user , `SFXAnsiStringConstRef` password ) Set the SMTP authorization method.
`SFCError`	SetFrom( `SFXAnsiStringConstRef` from ) Set the mail address of the sender.
`SFCError`	SetHostName( `SFXAnsiStringConstRef` host ) Set the host name of the sender.
`Void`	SetSSLMode( `Bool` isSSL ) Set the SSL connection mode.
`SFCError`	SetServer( `SFXSocketAddressConstRef` server ) Set the IP address and port number of the SMTP server.
`Void`	SetTrustMode( `UInt32` sslTrustMode ) Set the SSL trust mode.

Types
AuthEnum Constants that represent the SMTP authorization methods.
CallbackSPP Prototype of the callback function that is called when sending a SMTP mail is finished.
ProgressEnum Constants that show the progress statuses of sending a SMTP mail.

SFXSMTPSender::SFXSMTPSender

Constructor of SFXSMTPSender class.

[ public, explicit ]
SFXSMTPSender(Void);

Description

The resources necessary to send a SMTP mail are not allocated immediately after the SFXSMTPSender instance is created by this constructor.

When calling the SFXSMTPSender::SendMessage or SFXSMTPSender::SendText function, those resources will be allocated.

Reference

SFXSMTPSender::~SFXSMTPSender

SFXSMTPSender::~SFXSMTPSender

Destructor of SFXSMTPSender class.

[ public ]
~SFXSMTPSender(Void);

Description

When sending a SMTP mail is in progress, release this instance after canceling it using the SFXSMTPSender::Cancel function.

Reference

SFXSMTPSender::SFXSMTPSender

SFXSMTPSender::AddTo

Add the mail address of recipient.

[ public ]
SFCError AddTo(
    SFXAnsiStringConstRef to   // mail address of recipient
);

Argument

to

Mail address of recipient.

Mail address needs to be enclosed by "<>".

Specify the <admin@example.com> string if you want to send a mail to admin@example.com.

Return value

Success : SFERR_NO_ERROR
If insufficient memory : SFERR_NO_MEMOERY
If failed : SFERR_FAILED

Description

To set more than one mail address of recipient, call the SFXSMTPSender::AddTo function multiple times.

It is necessary to use the SFXSMTPSender::AddTo function before calling the SFXSMTPSender::SendText function.

Reference

SFXSMTPSender::ClearTo | SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::Cancel

Cancel sending a SMTP mail.

[ public ]
Void Cancel(Void);

Description

Cancel the sending of a SMTP mail, and then all the allocated resources will be released.

Reference

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::ClearTo

Delete all the mail addresses of recipients.

[ public ]
Void ClearTo(Void);

Description

Delete all the mail addresses of recipients set by the SFXSMTPSender::AddTo function.

Reference

SFXSMTPSender::AddTo

SFXSMTPSender::GetProgress

Get the progress status of sending a SMTP mail.

[ public, const ]
ProgressEnum GetProgress(Void);

Return value

Return the progress status of sending a SMTP mail.

	About the return value of the SFXSMTPSender::GetProgress function
	Detailed information : `SFXSMTPSender::ProgressEnum`

Description

If sending a SMTP mail failed, call the SFXSMTPSender::GetProgress function in the callback function to get the stage where an error occurred.

Reference

SFXSMTPSender::ProgressEnum

SFXSMTPSender::GetSFXSMTP

Get the instance of the SFXSMTP class that is internally used.

[ public ]
SFXSMTPRef GetSFXSMTP(Void);

Reference

SFXSMTP

SFXSMTPSender::GetSSLMode

Get the SSL connection mode.

[ public, const ]
Bool GetSSLMode(Void);

Return value

If valid : true
If invalid : false

Reference

SFXSMTPSender::SetSSLMode

SFXSMTPSender::GetTrustMode

Get the SSL trust mode.

[ public, const ]
UInt32 GetTrustMode(Void);

Description

The SSL trust mode can be one of the following values.

SSL_TRUST_MODE_FAIL
SSL_TRUST_MODE_CHECK
SSL_TRUST_MODE_IGNORE
SSL_TRUST_MODE_ALWAYS

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXSMTPSender::SetTrustMode

SFXSMTPSender::IsQuit

Check whether the QUIT command has been sent or not.

[ public ]
Bool IsQuit(Void);

Return value

If yes : true
Otherwise : false

SFXSMTPSender::SendMessage

Send the mail message.

[ public ]
SFCError SendMessage(
    SFXMailMessagePtr message   // mail message to send
    CallbackSPP spp             // callback function
    VoidPtr reference           // argument to callback function
);

Return value

Success : SFERR_NO_ERROR
If there is an invalid character : SFERR_INVALID_FORMAT
If content of the mail message is not correct : SFERR_INVALID_PARAM
If socket has already been opened, or failed to connect : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY
If failed : SFERR_FAILED
If failed to creating a socket : AEE_NET_ERROR

Description

Set the SMTP server using the SFXSMTPSender::SetServer function before sending.

Although the hostname of the sender is automatically obtained, it can be set using the SFXSMTPSender::SetHostName function.

The mail address of the sender is the From field included in the mail message header.

The mail addresses of the recipients are the To / Cc / Bcc fields included in the mail message header. The Bcc fields are deleted and sent.

	Result of sending a SMTP mail
	The result of sending a SMTP mail is notified to the callback function. It is not reflected in the return value of the SFXSMTPSender::SendMessage function.

Reference

SFXSMTPSender::SetServer | SFXSMTPSender::SetHostName | SFXSMTPSender::SetFrom | SFXSMTPSender::AddTo |

SFXSMTPSender::SendText

Send the mail text.

[ public ]
SFCError SendText(
    SFXAnsiStringConstRef text   // text to send
    CallbackSPP spp              // callback function
    VoidPtr reference            // data passed to callback function
);

Return value

Success : SFERR_NO_ERROR
If the host name or mail address of sender, or the mail address of recipient has not been set yet : SFERR_INVALID_PARAM
If socket has already been opened or failed to connect : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY
If failed : SFERR_FAILED
If failed to create a socket : AEE_NET_ERROR

Description

Send the mail text that consists of a header and a body. The header of the mail text includes the host name and mail address of sender, and the mail address of recipient.

How to use the SFXSMTPSender::SendText function

Before sending a mail, set the SMTP server, the host name of the sender, the mail address of the sender, and the mail address of the recipient using the SFXSMTPSender::SetServer, SFXSMTPSender::SetHostName, SFXSMTPSender::SetFrom, and SFXSMTPSender::AddTo functions respectively.

And then to send a mail, call the SFXSMTPSender::SendText function specifiying the mail text including the header as the first argument.

	Result of sending a SMTP mail
	The result of sending a SMTP mail is notified to the callback function. It is not reflected in the return value of SFXSMTPSender::SendText function.

Reference

SFXSMTPSender::SendMessage | SFXSMTPSender::SetServer | SFXSMTPSender::SetHostName | SFXSMTPSender::SetFrom | SFXSMTPSender::AddTo

SFXSMTPSender::SetAuthorization

Set the SMTP authorization method.

[ public ]
SFCError SetAuthorization(
    AuthEnum auth                    // authorization method
    SFXAnsiStringConstRef user       // username
    SFXAnsiStringConstRef password   // password
);

Argument

auth

Specify the authorization method.

Related information: SFXSMTPSender::AuthEnum Constants

user

Specify username.

password

Specify password.

Return value

Success : SFERR_NO_ERROR
If insufficient memory : SFERR_NO_MEMOERY

Description

If the SFXSMTPSender::SetAuthorization function is not called, communication will be done without the SMTP authorization.

Example

SFXSMTPSender sender;
SFCError error;

// authenticate SMTP by LOGIN authorization method
error = _sender.SetAuthorization(SFXSMTPSender::AUTH_LOGIN , "user" , "password");
if (error != SFERR_NO_ERROR) {
     TRACE("Authorization error : %d", error);
}

Reference

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetFrom

Set the mail address of the sender.

[ public ]
SFCError SetFrom(
    SFXAnsiStringConstRef from   // sender's mail address
);

Argument

from

Mail address of the sender

Mail address must be enclosed by "<>".

Specify <foobar@example.org> character string if you want to send mail to foobar@exapmle.org.

Return value

Success : SFERR_NO_ERROR
If insufficient memory : SFERR_NO_MEMOERY

Description

The SFXSMTPSender::SetFrom function must be called before the SFXSMTPSender::SendText function.

Reference

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetHostName

Set the host name of the sender.

[ public ]
SFCError SetHostName(
    SFXAnsiStringConstRef host   // host name
);

Argument

hostName

Sender's host name.

Empty string is not permitted.

Return value

Success : SFERR_NO_ERROR
If insufficient memory : SFERR_NO_MEMOERY

Description

The SFXSMTPSender::SetHostName function must be called before the SFXSMTPSender::SendText function.

The host name set by this function is used as an argument of the EHLO or HELO command of the SMTP protocol.

Reference

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetSSLMode

Set the SSL connection mode.

[ public ]
Void SetSSLMode(
    Bool isSSL   // whether or not to use the SSL connection
);

Description

To use the SSL connection, set true to the isSSL parameter.

SFXSMTPSender::SetServer

Set the IP address and port number of the SMTP server.

[ public ]
SFCError SetServer(
    SFXSocketAddressConstRef server   // IP address and port number of SMTP server
);

Argument

server: IP address and port number of the SMTP server.

Return value

Success : SFERR_NO_ERROR
If insufficient memory : SFERR_NO_MEMOERY

Reference

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetTrustMode

Set the SSL trust mode.

[ public ]
Void SetTrustMode(
    UInt32 sslTrustMode   // SSL trust mode
);

Argument

sslTrustMode

One of the following values are available for the SSL trust mode:

SSL_TRUST_MODE_FAIL: Default, fail on trust errors.
SSL_TRUST_MODE_CHECK: Suspend on trust errors so they can be checked and ignored.
SSL_TRUST_MODE_IGNORE: Ignore all trust errors.
SSL_TRUST_MODE_ALWAYS: Always suspend so trust can always be checked.

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXSSLSocket::SetTrustMode

SFXSMTPSender::AuthEnum

Constants that represent the SMTP authorization methods.

enum AuthEnum {
    AUTH_NONE,
    AUTH_PLAIN,
    AUTH_LOGIN,
    AUTH_CRAM_MD5,
    AUTH_DIGEST_MD5
};

Description

To set the SMTP authorization method, use the SFXSMTP::SendAuthCommand function.

Related information: SFXSMTP::SendAuthCommand

AUTH_NONE: SMTP authorization is not used.
AUTH_PLAIN: Represent the PLAIN authorization.
AUTH_LOGIN: Represent the LOGIN authorization.
AUTH_CRAM_MD5: Represent the CRAM-MD5 authorization.
AUTH_DIGEST_MD5: Represent the DIGEST-MD5 authorization (in the current version, the DIGEST-MD5 authorization cannot be used)

Reference

SFXSMTP::SendAuthCommand

SFXSMTPSender::CallbackSPP

Prototype of the callback function that is called when sending a SMTP mail is finished.

typedef Void(* SFXSMTPSender::CallbackSPP)(SFCError error, VoidPtr reference)

Description

The SFXSMTPSender::CallbackSPP function is the callback function called when sending a SMTP mail is finished.

To register this function, use the SFXSMTPSender::SendMessage or SFXSMTPSender::SendText function.

The result of sending a SMTP mail is obtained in this callback function.

As for the 1st argument "error": SFERR_NO_ERROR will be set if sending a SMTP mail succeeds, but an error code other than SFERR_NO_ERROR will be set if it fails.

As for the 2nd argument "reference": Same as the argument of the SFXSMTPSender::SendMessage or SFXSMTPSender::SendText function (in general, instance of the SFXSMTPSender class).

If sending a SMTP mail fails, call the SFXSMTPSender::GetProgress function in the callback function to get the stage where an error occurred.

Reference

SFXSMTPSender::GetProgress

SFXSMTPSender::ProgressEnum

Constants that show the progress statuses of sending a SMTP mail.

enum ProgressEnum {
    PROGRESS_NONE,
    PROGRESS_CONNECT,
    PROGRESS_EHLO,
    PROGRESS_HELO,
    PROGRESS_AUTH,
    PROGRESS_AUTHRESP1,
    PROGRESS_AUTHRESP2,
    PROGRESS_MAIL,
    PROGRESS_RCPT,
    PROGRESS_DATA,
    PROGRESS_DATATEXT,
    PROGRESS_QUIT,
    PROGRESS_ERRORQUIT,
    PROGRESS_DONE
};

Description

Constants that show the progress status of sending a SMTP mail with the SFXSMTPSender.

The following values can be obtained using the SFXSMTPSender::GetProgress function.

PROGRESS_NONE: The connection is not started.
PROGRESS_CONNECT: Connection to the SMTP server is in progress.
PROGRESS_EHLO: Waiting for the response of the EHLO command.
PROGRESS_HELO: Waiting for the response of the HELO command
PROGRESS_AUTH: Waiting for the response of the AUTH command
PROGRESS_AUTHRESP1: Waiting for the response regarding the command of the first SMTP authorization.
PROGRESS_AUTHRESP2: Waiting for the response regarding the command of the second SMTP authorization.
PROGRESS_MAIL: Waiting for the response of the MAIL command.
PROGRESS_RCPT: Waiting for the response of the RCPT command.
PROGRESS_DATA: Waiting for the response of the DATA command.
PROGRESS_DATATEXT: Waiting for the response of the message text following the DATA command.
PROGRESS_QUIT: Waiting for the response of the QUIT command.
PROGRESS_DONE: Sending a SMTP mail is finished.

Reference

SFXSMTPSender::GetProgress