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 SFXSMTPSender instance.
Create the SFXMailMessage instance, 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 835. The method to send a mail using the SFXSMTPSender class

class MyClass {
private:
    SFXSMTPSender _sender;
    XALLBACK_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 the completion of sending mail
    if ((error = _sender.SendMessage(&message,
        XALLBACK_INTERNAL(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 the completion of sending mail
XALLBACK_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);
    }
}

In the SFXMailMessage instance, the From field and the To field need to be set. The Cc and Bcc fileds can be set if neccessary.

The mail can be sent by the SFXSMTPSender::SendText function without using the 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

SFXMailMessage | SFXSMTP | SFXSMTPSender::SendText | Mail Sending

Member

Constructor/Destructor
SFXSMTPSender( `Void` ) Constructor of the SFXSMTPSender class.
~SFXSMTPSender( `Void` ) Destructor of the 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 SFXSMTP instance 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 or not the QUIT command has been sent.
`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 sender.
`SFCError`	SetHostName( `SFXAnsiStringConstRef` host ) Set the host name of 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 Type that represents the callback function to notify the completion of the SMTP mail sending.
ProgressEnum Constants that show the progress statuses of sending a SMTP mail.

SFXSMTPSender::SFXSMTPSender

Constructor of the SFXSMTPSender class.

[ public, explicit ]
SFXSMTPSender(Void);

Description

This constructor does the initialization as follows:

Initialize the progress status of the SMTP mail sending to PROGRESS_NONE(SFXSMTPSender::ProgressEnum).
Set the SMTP authorizarion to AUTH_NONE(see: SFXSMTPSender::SetAuthorization).
Turn the SSL connection mode off(see: SFXSMTPSender::SetSSLMode).
Set the SSL trust mode to SSL_TRUST_MODE_FAIL(see: SFXSMTPSender::SetTrustMode).

Note

	Note
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.

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::SetAuthorization | SFXSMTPSender::SetSSLMode | SFXSMTPSender::SetTrustMode | SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::~SFXSMTPSender

Destructor of the SFXSMTPSender class.

[ public ]
~SFXSMTPSender(Void);

Description

This destructor calls the SFXSMTPSender::Cancel function to cancel the SMTP mail sending.

Reference

SFXSMTPSender::Cancel

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

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

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

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

Reference

SFXSMTPSender::ClearTo | SFXSMTPSender::SendText

SFXSMTPSender::Cancel

Cancel sending a SMTP mail.

[ public ]
Void Cancel(Void);

Description

This function cancels the SMTP mailsending, and then all the allocated resources will be released.

Concretely, the following processings will be done.

Cancel and stop the SMTP mail sending(see: SFXSMTP::Close).
Release the allocated resources.
Unregister callbacks for sending mails.
Initialize the progress status of the SMTP mail sending with PROGRESS_NONE(see: SFXSMTPSender::ProgressEnum).
Clear the From filed(sender mail address) and the To field(recipient mail address).
And initialize the other internal variables.

	Note
	This function is called in the `SFXSMTPSender::~SFXSMTPSender` destructor internally.

Reference

SFXSMTPSender::ClearTo

Delete all the mail addresses of recipients.

[ public ]
Void ClearTo(Void);

Description

This function deletes 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
	Reference: `SFXSMTPSender::ProgressEnum`

Description

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

Reference

SFXSMTPSender::ProgressEnum | SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::GetSFXSMTP

Get the SFXSMTP instance 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 the SSL connection mode is turned on: 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
	Reference: ISSL_NegotiateV in the BREW API Reference

Reference

SFXSMTPSender::SetTrustMode | BREW API ISSL_NegotiateV

SFXSMTPSender::IsQuit

Check whether or not the QUIT command has been sent.

[ public ]
Bool IsQuit(Void);

Return value

If yes: true
Otherwise: false

Reference

SFXSMTP::SendQuitCommand

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

If succeeds: SFERR_NO_ERROR
If invalid characters are included: 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 to creating a socket: AEE_NET_ERROR

Description

It is necessary to set the SMTP server using the SFXSMTPSender::SetServer function before sending the mail message with this function.

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 recipients are the To / Cc / Bcc fields included in the mail message header. The Bcc fields will be deleted when sending the mail.

	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 this function.

Reference

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

If succeeds: 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 to create a socket: AEE_NET_ERROR

Description

This function sends 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 this 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 this function.

Reference

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.

Reference: SFXSMTPSender::AuthEnum Constants

user

Specify username.

password

Specify password.

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

If this 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::AuthEnum | SFXSMTPSender::SendMessage | SFXSMTPSender::SendText | SFXSMTPSender::SFXSMTPSender

SFXSMTPSender::SetFrom

Set the mail address of 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

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

This function must be called before the SFXSMTPSender::SendText function.

Reference

SFXSMTPSender::SendText

SFXSMTPSender::SetHostName

Set the host name of sender.

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

Argument

hostName

Sender's host name.

Empty string is not permitted.

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

This 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::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, specifiy true in the isSSL argument.

Reference

SFXSMTPSender::GetSSLMode | SFXSMTPSender::SFXSMTPSender

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

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Reference

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText | SFXSMTPSender::SFXSMTPSender | SFXSocketAddress

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
	Reference: ISSL_NegotiateV in the BREW API Reference

Reference

SFXSMTPSender::GetTrustMode | SFXSSLSocket::SetTrustMode | SFXSMTPSender::SFXSMTPSender | BREW API ISSL_NegotiateV

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.

Reference: 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

SFXSMTPSender::SetAuthorization | SFXSMTP::SendAuthCommand | SFXSMTPSender::SFXSMTPSender

SFXSMTPSender::CallbackSPP

Type that represents the callback function to notify the completion of the SMTP mail sending.

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

Description

This function prototype represents 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.

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.

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::SendMessage | SFXSMTPSender::SendText | 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_ERRORQUIT: An error occurs in sending a SMTP mail.
PROGRESS_DONE: Sending a SMTP mail is finished.

Reference

SFXSMTPSender::GetProgress | SFXSMTPSender::SFXSMTPSender