SFXSMTPSender

SMTP メール送信クラスです。

#include <SFXSMTPSender.h.hpp>

class SFXSMTPSender;

SFMTYPEDEFCLASS(SFXSMTPSender)

協調図

解説

SFXSMTPSender クラスを使ってメールを送信する方法

SFXSMTPSender クラスのインスタンスを作成します。
SFXMailMessage クラスのインスタンス ( メールメッセージ）を作成します。
SFXSMTPSender::SetServer 関数で、SMTP サーバーの IP アドレスとポート番号を設定します。
SFXSMTPSender::SendMessage 関数で、作成したメールメッセージと、コールバック関数を登録します。SFXSMTPSender::SendMessage 関数を呼び出すとメール送信が開始します。

例 779. SMTP メール送信

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

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

    // メールヘッダーに From フィールドを設定する
    message.SetFromField("fromaddress@example.com");

    // メールヘッダーに To アドレスを追加する
    message.AddToField("toaddress1@example.com");
    message.AddToField("toaddress2@example.com");

    // メールヘッダーに Subject フィールドを設定する
    message.SetSubjectField("Mail Subject");

    // メールメッセージの本文を設定する
    message.SetBody("Mail test\r\nThis mail is sent by SFXSMTPSender.\r\n");

    // SMTP サーバーの IP アドレスとポート番号を指定する ( ドメインは自動解決される )
    _sender.SetServer(SFXSocketAddress("smtpserver.example.com:25"));

    // SMTPCallback コールバック関数を登録し、メールを送信する
    // メール送信の完了は SMTPCallback 関数に通知される
    if ((error = _sender.SendMessage(&message,
        XALLBACK_FUNCTION(SMTPCallback))) != SFERR_NO_ERROR) {
        // error が SFERR_NO_ERROR でない場合はコールバックが戻らないので、
        // ここでエラー処理をする
    }
}

// メール送信の完了が通知されるコールバック関数
XALLBACK_IMPLEMENT_SFXSMTPSENDER(MyClass, SMTPCallback, error)
{
    if (error == SFERR_NO_ERROR) {
        TRACE("メールを送信しました。");
    }
    else {
        TRACE("メール送信に失敗しました。 %d", error);
    }
}

SFXMailMessage クラスのインスタンスは、From フィールドと To フィールドを設定する必要があります。Cc フィールド、Bcc フィールドは必要に応じて設定します。

SFXMailMessage クラスを利用せずに、SFXSMTPSender::SendText 関数を使ってメールを送信することも可能です。この場合、メールヘッダーとメール本文からなるメールテキストを作成する必要があります。メールヘッダーには、送信元ホスト名、送信元メールアドレス、送信先メールアドレスなどの情報が含まれます。

参照

SFXSMTP | メール送信

メンバ

コンストラクタ/デストラクタ
SFXSMTPSender( `Void` ) SFXSMTPSender クラスのコンストラクタです。
~SFXSMTPSender( `Void` ) SFXSMTPSender クラスのデストラクタです。

パブリック関数
`SFCError`	AddTo( `SFXAnsiStringConstRef` to ) 送信先メールアドレスを追加します。
`Void`	Cancel( `Void` ) SMTP メール送信をキャンセルします。
`Void`	ClearTo( `Void` ) 送信先メールアドレスを全て削除します。
`ProgressEnum`	GetProgress( `Void` ) SMTP メール送信の進行状態を取得します。
`SFXSMTPRef`	GetSFXSMTP( `Void` ) 内部で使用している SFXSMTP クラスのインスタンスを取得します。
`Bool`	GetSSLMode( `Void` ) SSL 接続モードを取得します。
`UInt32`	GetTrustMode( `Void` ) SSL 認証モードを取得します。
`Bool`	IsQuit( `Void` ) QUIT コマンドを送信したかどうかを判定します。
`SFCError`	SendMessage( `SFXMailMessagePtr` message , `CallbackSPP` spp , `VoidPtr` reference ) メールメッセージを送信します。
`SFCError`	SendText( `SFXAnsiStringConstRef` text , `CallbackSPP` spp , `VoidPtr` reference ) メールテキストを送信します。
`SFCError`	SetAuthorization( `AuthEnum` auth , `SFXAnsiStringConstRef` user , `SFXAnsiStringConstRef` password ) SMTP 認証の方式を設定します。
`SFCError`	SetFrom( `SFXAnsiStringConstRef` from ) 送信元メールアドレスを設定します。
`SFCError`	SetHostName( `SFXAnsiStringConstRef` host ) 送信元のホストネームを設定します。
`Void`	SetSSLMode( `Bool` isSSL ) SSL 接続モードを設定します。
`SFCError`	SetServer( `SFXSocketAddressConstRef` server ) SMTP サーバーの IP アドレスとポート番号を設定します。
`Void`	SetTrustMode( `UInt32` sslTrustMode ) SSL 認証モードを設定します。

型
AuthEnum SMTP 認証方式を表す定数です。
CallbackSPP SMTP メール送信終了時に呼び出されるコールバック関数のプロトタイプです。
ProgressEnum SMTP メール送信の進行状態を表す定数です。

SFXSMTPSender::SFXSMTPSender

SFXSMTPSender クラスのコンストラクタです。

[ public, explicit ]
SFXSMTPSender(Void);

解説

コンストラクタでインスタンスを作成した直後は、SMTP メール送信に必要なリソースは割り当てられていません。

SMTP メール送信に必要なリソースは SFXSMTPSender::SendMessage 関数、または SFXSMTPSender::SendText 関数を呼び出したときに確保されます。

参照

SFXSMTPSender::~SFXSMTPSender

SFXSMTPSender::~SFXSMTPSender

SFXSMTPSender クラスのデストラクタです。

[ public ]
~SFXSMTPSender(Void);

解説

SMTP メール送信中のときは、SFXSMTPSender::Cancel 関数を呼び出して SMTP メール送信をキャンセルしてからインスタンスを破棄します。

参照

SFXSMTPSender::SFXSMTPSender

SFXSMTPSender::AddTo

送信先メールアドレスを追加します。

[ public ]
SFCError AddTo(
    SFXAnsiStringConstRef to   // 送信先メールアドレス
);

引数

to

追加する送信先のメールアドレスです。

メールアドレスは、"<>" で囲む必要があります。

admin@exapmle.com に送信する場合、文字列 <admin@example.com> を指定します。

戻り値

成功したとき : SFERR_NO_ERROR
メモリ不足のとき : SFERR_NO_MEMOERY
失敗したとき : SFERR_FAILED

解説

複数の送信先メールアドレスを設定するには、SFXSMTPSender::AddTo 関数を複数回呼び出します。

SFXSMTPSender::AddTo 関数は SFXSMTPSender::SendText 関数を呼び出す前に必ず使う必要があります。

参照

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

SFXSMTPSender::Cancel

SMTP メール送信をキャンセルします。

[ public ]
Void Cancel(Void);

解説

SMTP メール送信を中断・終了し、確保したリソースを解放します。

参照

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::ClearTo

送信先メールアドレスを全て削除します。

[ public ]
Void ClearTo(Void);

解説

SFXSMTPSender::AddTo 関数で設定した送信先メールアドレスを全て削除します。

参照

SFXSMTPSender::AddTo

SFXSMTPSender::GetProgress

SMTP メール送信の進行状態を取得します。

[ public, const ]
ProgressEnum GetProgress(Void);

戻り値

SMTP メール送信の進行状態です。

	SFXSMTPSender::GetProgress 関数の戻り値について
	詳細情報 : `SFXSMTPSender::ProgressEnum`

解説

SMTP メール送信が失敗したとき、コールバック関数から SFXSMTPSender::GetProgress 関数を呼び出すと、SMTP メール送信エラーが起こった段階を取得できます。

参照

SFXSMTPSender::ProgressEnum

SFXSMTPSender::GetSFXSMTP

内部で使用している SFXSMTP クラスのインスタンスを取得します。

[ public ]
SFXSMTPRef GetSFXSMTP(Void);

参照

SFXSMTP

SFXSMTPSender::GetSSLMode

SSL 接続モードを取得します。

[ public, const ]
Bool GetSSLMode(Void);

戻り値

有効なとき : true
無効なとき : false

参照

SFXSMTPSender::SetSSLMode

SFXSMTPSender::GetTrustMode

SSL 認証モードを取得します。

[ public, const ]
UInt32 GetTrustMode(Void);

参照

SFXSMTPSender::SetTrustMode

SFXSMTPSender::IsQuit

QUIT コマンドを送信したかどうかを判定します。

[ public ]
Bool IsQuit(Void);

戻り値

送信したとき : true
送信していないとき : false

SFXSMTPSender::SendMessage

メールメッセージを送信します。

[ public ]
SFCError SendMessage(
    SFXMailMessagePtr message   // 送信するメールメッセージ
    CallbackSPP spp             // コールバック関数
    VoidPtr reference           // コールバックへの引数
);

戻り値

成功したとき : SFERR_NO_ERROR
不正な文字があるとき : SFERR_INVALID_FORMAT
メールメッセージの内容が正しくないとき : SFERR_INVALID_PARAM
ソケットが既にオープンしているとき、または接続の確立に失敗したとき : SFERR_INVALID_STATE
メモリ不足のとき : SFERR_NO_MEMORY
失敗したとき : SFERR_FAILED
ソケットの作成に失敗したとき : AEE_NET_ERROR

解説

送信前に SMTP サーバーを SFXSMTPSender::SetServer 関数で設定します。

送信元のホスト名は自動的に取得されますが、SFXSMTPSender::SetHostName 関数で設定することも可能です。

メールの送信元は、メールメッセージのヘッダーに含まれる From フィールドです。

メールの送信先は、メールメッセージのヘッダーに含まれる To / Cc / Bcc フィールドです。Bcc フィールドは削除して送信します。

	SMTP メール送信の結果
	SMTP メール送信の結果は、コールバック関数に通知されます。SFXSMTPSender::SendMessage 関数の戻り値には反映されません。

参照

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

SFXSMTPSender::SendText

メールテキストを送信します。

[ public ]
SFCError SendText(
    SFXAnsiStringConstRef text   // 送信するテキスト
    CallbackSPP spp              // コールバック関数
    VoidPtr reference            // コールバック関数へ渡すデータ
);

戻り値

成功したとき : SFERR_NO_ERROR
送信元ホスト名、送信元メールアドレス、送信先メールアドレスのいずれかを設定していないとき : SFERR_INVALID_PARAM
ソケットが既にオープンしているとき、または接続の確立に失敗したとき : SFERR_INVALID_STATE
メモリ不足のとき : SFERR_NO_MEMORY
失敗したとき : SFERR_FAILED
ソケットの作成に失敗したとき : AEE_NET_ERROR

解説

ヘッダーと本文からなるメールテキストを送信します。メールヘッダーには、送信元ホスト名、送信元メールアドレス、送信先メールアドレスなどの情報が含まれます。

SFXSMTPSender::SendText 関数の使用方法

送信前に、SFXSMTPSender::SetServer、SFXSMTPSender::SetHostName、SFXSMTPSender::SetFrom、SFXSMTPSender::AddTo 関数を使って、 SMTP サーバー、送信元ホスト名、送信元メールアドレス、送信先メールアドレスをそれぞれ設定します。

ヘッダーを含むメール本文を第 1 引数にして SFXSMTPSender::SendText 関数の呼び出すと、メール送信が開始します。

	SMTP メール送信の結果
	SMTP メール送信の結果は、コールバック関数に通知されます。SFXSMTPSender::SendText 関数の戻り値には反映されません。

参照

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

SFXSMTPSender::SetAuthorization

SMTP 認証の方式を設定します。

[ public ]
SFCError SetAuthorization(
    AuthEnum auth                    // 認証方式
    SFXAnsiStringConstRef user       // ユーザー名
    SFXAnsiStringConstRef password   // パスワード
);

引数

auth

認証方式を指定します。

関連情報 : SFXSMTPSender::AuthEnum 定数

user

ユーザー名を指定します。

password

パスワードを指定します。

戻り値

成功したとき : SFERR_NO_ERROR
メモリ不足のとき : SFERR_NO_MEMOERY

解説

SFXSMTPSender::SetAuthorization 関数を呼び出さない場合は、SMTP 認証無しで通信します。

使用例

SFXSMTPSender sender;
SFCError error;

// LOGIN 認証方式で SMTP 認証を行う
error = _sender.SetAuthorization(SFXSMTPSender::AUTH_LOGIN , "user" , "password");
if (error != SFERR_NO_ERROR) {
     TRACE("Authorization error : %d", error);
}

参照

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetFrom

送信元メールアドレスを設定します。

[ public ]
SFCError SetFrom(
    SFXAnsiStringConstRef from   // 送信元メール アドレス
);

引数

from

送信元のメールアドレスです。

メールアドレスは、"<>" で囲まなくてはなりません。

foobar@exapmle.org が送信元の場合、文字列 <foobar@example.org> を指定します。

戻り値

成功したとき : SFERR_NO_ERROR
メモリ不足のとき : SFERR_NO_MEMOERY

解説

SFXSMTPSender::SetFrom 関数は SFXSMTPSender::SendText 関数を呼び出す前に必ず使う必要があります。

参照

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetHostName

送信元のホストネームを設定します。

[ public ]
SFCError SetHostName(
    SFXAnsiStringConstRef host   // ホスト ネーム
);

引数

hostName

送信元のホストネームです。

空文字列は使えません。

戻り値

成功したとき : SFERR_NO_ERROR
メモリ不足のとき : SFERR_NO_MEMOERY

解説

SFXSMTPSender::SetHostName 関数は SFXSMTPSender::SendText 関数を呼び出す前に必ず使う必要があります。

SFXSMTPSender::SetHostName 関数で設定したホストネームは、SMTP プロトコルの EHLO ( もしくは HELO )コマンドの引数として使われます。

参照

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetSSLMode

SSL 接続モードを設定します。

[ public ]
Void SetSSLMode(
    Bool isSSL   // SSL 接続を使うかどうか
);

解説

SSL 接続を使うには、isSSL パラメータを true に設定します。

SFXSMTPSender::SetServer

SMTP サーバーの IP アドレスとポート番号を設定します。

[ public ]
SFCError SetServer(
    SFXSocketAddressConstRef server   // SMTP サーバーの IP アドレスとポート番号
);

引数

server: SMTP サーバーの IP アドレスとポート番号です。

戻り値

成功したとき : SFERR_NO_ERROR
メモリ不足のとき : SFERR_NO_MEMOERY

参照

SFXSMTPSender::SendMessage | SFXSMTPSender::SendText

SFXSMTPSender::SetTrustMode

SSL 認証モードを設定します。

[ public ]
Void SetTrustMode(
    UInt32 sslTrustMode   // SSL 認証モード
);

引数

sslTrustMode

SSL 認証方法は 4 つあります：

SSL_TRUST_MODE_FAIL ( デフォルトです。認証エラーがあると接続が失敗します。)
SSL_TRUST_MODE_CHECK ( 認証エラーの場合、チェックまたは無効にできるように中断します。)
SSL_TRUST_MODE_IGNORE ( すべての認証エラーを無効にします。)
SSL_TRUST_MODE_ALWAYS ( 認証をチェックできるように常に中断します。)

戻り値

成功したとき : SFERR_NO_ERROR
ソケットが閉じているとき : SFERR_INVALID_STATE

参照

SFXSSLSocket::SetTrustMode

SFXSMTPSender::AuthEnum

SMTP 認証方式を表す定数です。

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

解説

SFXSMTP::SendAuthCommand で、SMTP認証の方式を設定するときに使います。

関連情報 : SFXSMTP::SendAuthCommand

AUTH_NONE: SMTP 認証を使わないことを表します。
AUTH_PLAIN: PLAIN 認証を表します。
AUTH_LOGIN: LOGIN 認証を表します。
AUTH_CRAM_MD5: CRAM-MD5 認証を表します。
AUTH_DIGEST_MD5: DIGEST-MD5 認証を表します。( 現バージョンでは、DIGEST-MD5 認証は使用できません。)

参照

SFXSMTP::SendAuthCommand

SFXSMTPSender::CallbackSPP

SMTP メール送信終了時に呼び出されるコールバック関数のプロトタイプです。

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

解説

SMTP メール送信終了時に呼び出されるコールバック関数です。

このコールバック関数は SFXSMTPSender::SendMessage または SFXSMTPSender::SendText 関数を使って登録します。

メール送信処理の結果は、このコールバック関数から取得します。

第 1 引数の error には、SMTP メール送信に成功した場合は SFERR_NO_ERROR、失敗した場合はその他のエラーコードが設定されます。

第 2 引数の reference には、SFXSMTPSender::SendMessage または SFXSMTPSender::SendText 関数で指定したパラメータ( 通常、SFXSMTPSender クラスのインスタンス)を指定します。

SMTP メール送信処理のどの段階でエラーが発生したかは、コールバック関数内で SFXSMTPSender::GetProgress 関数を使って取得できます。

参照

SFXSMTPSender::GetProgress

SFXSMTPSender::ProgressEnum

SMTP メール送信の進行状態を表す定数です。

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
};

解説

SFXSMTPSender クラスによる SMTP メール送信の進行状態を表す定数です。

SFXSMTPSender::GetProgress 関数を使って以下の値を取得できます。

PROGRESS_NONE: 接続は開始されていません。
PROGRESS_CONNECT: SMTP サーバーに接続中です。
PROGRESS_EHLO: EHLO コマンドの応答を待っています。
PROGRESS_HELO: HELO コマンドの応答を待っています。
PROGRESS_AUTH: AUTH コマンドの応答を待っています。
PROGRESS_AUTHRESP1: SMTP 認証の1回目のコマンドに対する応答を待っています。
PROGRESS_AUTHRESP2: SMTP 認証の2回目のコマンドに対する応答を待っています。
PROGRESS_MAIL: MAIL コマンドの応答を待っています。
PROGRESS_RCPT: RCPT コマンドの応答を待っています。
PROGRESS_DATA: DATA コマンドの応答を待っています。
PROGRESS_DATATEXT: DATA コマンドに続くメッセージテキストの応答を待っています。
PROGRESS_QUIT: QUIT コマンドの応答を待っています。
PROGRESS_DONE: メール送信処理がすべて完了した状態です。

参照

SFXSMTPSender::GetProgress