16.4. Sending and Receiving Mails

16.4.1. Mail Overview

There are three types of classes for sending and receiving mails.

Table 16.3. Classes for Sending and Receiving Mails

Class Name	Description
`SFXSMTPSender`	Class for sending a SMTP mail.
`SFXPOP3Receiver`	Class for receiving a POP3 mail.
`SFXMailMessage`	Class for processing a mail message.

The following classes are used to process SMTP and the POP3 protocol at the detailed level.

Table 16.4. SMTP/POP3 protocol classes

Class Name	Description
`SFXSMTP`	Class for processing the SMTP protocol.
`SFXPOP3`	Class for processing the POP3 protocol.
`SFXMailUtility`	Utility class for processing a mail message.
`SFXMailField`	Class for encode and decode the mail header.

	About MIF File Setting
	Never forget to turn on the Network option in the MIF file setting of privilege level.

16.4.2. Sending Mail

SFXSMTPSender class is used to send mails.

Example 16.16. Send mails

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

// precondition: sufficient memory
Void MyClass::Start(Void)
{
    SFCError error;
    SFXMailMessage message;

    // set From Address
    message.SetFromField("fromaddress@example.com");

    // set To Address
    message.AddToField("toaddress1@example.com");
    message.AddToField("toaddress2@example.com");

    // set title
    message.SetSubjectField("Mail Subject");

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

    // set mail server and port number for mail sending (domain is automatically resolved)
    _sender.SetServer(SFXSocketAddress("smtpserver.example.com:25"));

    // register SMTPCallback as callback function, and then send mail
    // completion of sending mail will be notified to SMTPCallback function
    if ((error = _sender.SendMessage(&message,
        XALLBACK_INTERNAL(SMTPCallback))) != SFERR_NO_ERROR) {
        // if an error occurs, SMTPCallback callback function will not be called
        // error handling
        ...
    }
}

// callback function notified of the completion of sending mail
XALLBACK_IMPLEMENT_SFXSMTPSENDER(MyClass, SMTPCallback, error)
{
    if (error == SFERR_NO_ERROR) {
        TRACE("The mail has been sent.");
    }
    else {
        TRACE("Failed to send the mail.%d", error);
    }
}

16.4.3. Receiving Mails

SFXPOP3Receiver is used to receive mails.

Example 16.17. Receive mails

class MyClass {
private:
    SFXPOP3Receiver _receiver;
    XALLBACK_DECLARE_SFXPOP3RECEIVER(POP3Callback)
public:
    Void Start(Void);
};

// precondition: sufficient memory
Void MyClass::Start(Void)
{
    // set account
    _receiver.SetAccount("user", "password");

    // set mail server and portnumber for mail receiving (domain is automatically resolved)
    _receiver.SetServer(SFXSocketAddress("pop3server.example.com:110"));

    // register POP3Callback as callback function, and then receive mails
    // completion of receiving mails will be notified to POP3Callback function
    if ((error = _receiver.Receive(XALLBACK_INTERNAL(POP3Callback)))
        != SFERR_NO_ERROR) {
        // if an error occurs, POP3Callback callback function will not be called
        // error handling
        ...
    }
}

// callback function notified of the completion of receiving mails
XALLBACK_IMPLEMENT_SFXPOP3RECEIVER(MyClass, POP3Callback, error)
{
    SInt32 i;

    if (error == SFERR_NO_ERROR) { 
        // succeed to receive mails

        // get mails
        SFXPOP3Receiver::MailArrayConstRef mailArray = receiver.GetReceivedMailArray();

        // display the number of mails
        TRACE("received %d mails", mailArray.GetSize());

        for (i = 0; i < mailArray.GetSize() ; i++) {
            SFXPOP3Receiver::MailInfoPtr minfo = mailArray[i];

            // get (from left): mail size, UIDL, mail body including header
            TRACE("%d, %s, %s", minfo->size, minfo->uidl.GetCString(), minfo->mail.GetCString());

        }
    }
}

16.4.4. Sending Mails through SSL

The only difference between common mail sending and SSL mail sending is that, for SSL mail sending, SetSSLMode(), SetTrustMode(), and SetAuthorization() are used.

Example 16.18. Send mails through SSL

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

// precondition: sufficient memory
// bold lines are added
Void MyClass::Start(Void)
{
    SFCError error;
    SFXMailMessage message;

    // set From address
    message.SetFromField("fromaddress@example.com");

    // set To address
    message.AddToField("toaddress1@example.com");
    message.AddToField("toaddress2@example.com");

    // set title
    message.SetSubjectField("Mail Subject");

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

    // set mail server and port number for mail sending (domain is automatically resolved)
    _sender.SetServer(SFXSocketAddress("smtpserver.example.com:465"));

    // SSL mail sending settings
    _sender.SetSSLMode(true);                                       // set SSL connect mode
    _sender.SetTrustMode(SSL_TRUST_MODE_FAIL);                      // set trust mode
    _sender.SetAuthorization(AUTH_CRAM_MD5,"username","password");  // set SMPT authentication mode

    // register SMTPCallback as callback function, and then send mail
    // completion of sending mail will be notified to SMTPCallback function
    if ((error = _sender.SendMessage(&message,
        XALLBACK_INTERNAL(SMTPCallback))) != SFERR_NO_ERROR) {
        // if an error occurs, SMTPCallback callback function will not be called
        // error handling
        ...
    }
}

// callback function notified of the completion of sending mail
XALLBACK_IMPLEMENT_SFXSMTPSENDER(MyClass, SMTPCallback, error)
{
    if (error == SFERR_NO_ERROR) {
        TRACE("The mail has been sent.");
    }
    else {
        TRACE("Failed to send the mail.%d", error);
    }
}

16.4.5. Receiving Mails through SSL

The only difference between common mail receiving and SSL mail receiving is that, for SSL mail receiving, SetSSLMode() and SetTrustMode() are used.

Example 16.19. Receive mails through SSL

class MyClass {
private:
    SFXPOP3Receiver _receiver;
    XALLBACK_DECLARE_SFXPOP3RECEIVER(POP3Callback)
public:
    Void Start(Void);
};

// precondition: sufficient memory
// bold lines are added
Void MyClass::Start(Void)
{
    // set account
    _receiver.SetAccount("user", "password");

    // set mail server and port number from mail receiving(domain is automically resolved)
    _receiver.SetServer(SFXSocketAddress("pop3server.example.com:995"));

   // SSL mail receiving settings
   _receiver.SetSSLMode(true);                    // set SSL connect mode
   _receiver.SetTrustMode(SSL_TRUST_MODE_FAIL);   // set trust mode
 
    // register POP3Callback as callback function, and then receive mails
    // completion of receiving mails will be notified to POP3Callback function
    if ((error = _receiver.Receive(XALLBACK_INTERNAL(POP3Callback)))
        != SFERR_NO_ERROR) {
        // if an error occurs, POP3Callback callback function will not be called
        // error handling
        ...
    }
}

// callback function notified of the completion of receiving mails
XALLBACK_IMPLEMENT_SFXPOP3RECEIVER(MyClass, POP3Callback, error)
{
    SInt32 i;

    if (error == SFERR_NO_ERROR) { 
        // succeed to receive mails

        // get mails
        SFXPOP3Receiver::MailArrayConstRef mailArray = receiver.GetReceivedMailArray();

        // display the number of mails
        TRACE("received %d mails", mailArray.GetSize());

        for (i = 0; i < mailArray.GetSize() ; i++) {

            SFXPOP3Receiver::MailInfoPtr minfo = mailArray[i];

            // get (from left): mail size, UIDL, mail body including header
            TRACE("%d, %s, %s", minfo->size, minfo->uidl.GetCString(), minfo->mail.GetCString());

        }
    }
}

16.4.6. Mail Message

Mail message is the string with header and body and is treated using the SFXMailMessage class.

Using the SFXMailMessage class, you can create the mail message to send and the files to attach, parse the header of received mail and so on.

Example 16.20. Create the mail message

SFXMailMessage message;

// set From field of Header
message.ReplaceFromField("fromaddress@example.com");

// set To field of Header (this function can be called multiple times)
message.AddToField("toaddress1@example.com");

// set Subject field of Header
message.ReplaceSubjectField("title");

// set mail body
message.SetBody("Mail body");

// send mail message
smtpSender.SendMessage(&message, XALLBACK_INTERNAL(SMTPCallback));

Example 16.21. Parse the received mail

// mail message which is received 
SFXAnsiString string =
    "From: Albert Einstein <einstein@example.com>\r\n"
    "To: Isaac Newton <newton@example.com>\r\n"
    "Subject: untitled\r\n"
    "Date: Sat, 08 Mar 2008 20:37:58 +0900\r\n"
    "\r\n"
    "This is a mail body.\r\n";

SFXMailMessage message;

// parse mail message
message.Parse(receivedString);

// get From field from mail header
// fromString: "Albert Einstein <einstein@example.com>"
SFXAnsiString fromString = message.GetFromField();

// get To field from mail header
// toString: "Isaac Newton <newton@example.com>"
SFXAnsiString toString = message.GetToField();

// get Subject field from mail header
// subjectString: "untitled"
SFXAnsiString subjectString = message.GetSubjectField();

// get Date field from mail header as SFXDate instance
// date: "Sat, 08 Mar 2008 20:37:58 +0900"
SFXDate date = message.GetDateField();

// get Body
// bodyString: "This is a mail body.\r\n"
SFXAnsiString bodyString = message.GetBody();