Collaboration diagram

Description

Class to process the mail message that is defined in RFC2822 (Internet Message Format). With this class you can create, change, write, and parse mail messages. Multi-part message and attached file can also be processed.

	Encoding of the Subject field and the file name of attached data
	RFC2231(MIME Parameter Value and Encoded Word Extensions) is not supported.

Procedure to send a SMTP mail.

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

Void MyClass::Start(Void)
{
    SFCError error;
    SFXMailMessage message;
    
    // set Subject field to mail header
    message.SetSubjectField("Mail Subject");

    // set From field to mail header
    message.SetFromField("[email protected]");

    // add To address to mail header
    message.AddToField("[email protected]");
    message.AddToField("[email protected]");
    
    // add Cc address to mail header
    message.AddCcField("[email protected]");
    
    // add Bcc address to mail header
    message.AddBccField("[email protected]");
    
    // add Content Type to mail header
    message.AddField("Content-Type", "text");

    // set Body of mail message
    message.SetBody("Mail test\r\nThis mail is sent by SFXSMTPSender.\r\n");
    
    // create file name to attach
    SFXBuffer buff("Hello", 5);        
    attach file to the mail message
    message.AttachFile(buff, "filename.txt", "text", "plain");

    // specify 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) {
        TRACE("Mail has been sent.");
    }
    else {
        TRACE("Mail sending failed. %d", error);
    }
}

Procedure to receive a POP3 mail

	Processing of a multi-part message
	To process a multi-part message, use the SFXMailMessage::IsMultipart function.

// received mail message
SFXAnsiString receivedString =
    "From: Albert Einstein <[email protected]>\r\n"
    "To: Isaac Newton <[email protected]>\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 <[email protected]>"
SFXAnsiString fromString = message.GetFromField();

// get To field from mail header
// toString: "Isaac Newton <[email protected]>"
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();

Reference

SFXMailUtility | SFXMailField

Member

Description

This constructor does nothing.

Description

This destructor calls the SFXMailMessage::Clear function to clear the contents of this mail message.

Reference

SFXMailMessage::Clear

Argument

Return value

Reference

SFXMailMessage::GetBccField | SFXMailMessage::ReplaceBccField | SFXMailMessage::AddField

Argument

Return value

Reference

SFXMailMessage::GetCcField | SFXMailMessage::ReplaceCcField | SFXMailMessage::AddField

Argument

Return value

Description

Different from the SFXMailMessage::ReplaceField function, the SFXMailMessage::AddField function adds the value without deleting the existing values of the field.

For the fields such as From, To, etc. that can not have more than one value, use the SFXMailMessage::ReplaceField function to replace the existing value. For the fields such as Received that can have more than one value, use the SFXMailMessage::AddField function to add the value.

Reference

SFXMailMessage::ReplaceField | SFXMailMessage::HasField | SFXMailMessage::RemoveField | SFXMailMessage::GetField | SFXMailMessage::GetFieldList

Argument

Return value

Description

Set "multipart" to the Content-Type using SFXMailMessage::SetContentType function before calling the SFXMailMessage::AddMultipartBody function.

Reference

SFXMailMessage::AttachFile | SFXMailMessage::SetContentType | SFXMailMessage::IsMultipart

Argument

Return value

Reference

SFXMailMessage::GetToField | SFXMailMessage::ReplaceToField | SFXMailMessage::AddField

Argument

Return value

Description

The mail body should be set by the SFXMailMessage::SetBody before the SFXMailMessage::AttachFile function is called. At the time when the SFXMailMessage::AttatchFile function is called, the mail message comes to have the multi-part part even if the original message has no multi-part.

Attached data will be automatically encoded in the Base64 format.

The internal procedure to attach a file to the mail message is as follows:

Example

Attach a text file.

// attach to SFXMailMessage msg
msg.SetBody("Message Body");    // set Body before attaching file
SFXBuffer buff1("abc", 3);        // text file to be attached (file 1)
SFXBuffer buff2("defghij", 7);    // text file to be attached (file 2)
msg.AttachFile(buff1, "filename1.txt", "text", "plain");
msg.AttachFile(buff2, "filename2.txt", "text", "plain");

Reference

SFXMailMessage::AddMultipartBody | SFXMailMessage::IsMultipart

Reference

SFXMailMessage::~SFXMailMessage

Argument

Return value

Description

The file encoded in the Base64 format is automaticaly decoded.

	Encoding of the file name of attached data
	RFC2231(MIME Parameter Value and Encoded Word Extensions) is not supported.

Reference

SFXMailMessage::AttachFile | SFXMailMessage::AddMultipartBody | SFXMailMessage::IsMultipart | SFXMailMessage::GetMultipartSize

Argument

Return value

Return the value of Bcc field.

Reference

SFXMailMessage::AddBccField | SFXMailMessage::ReplaceBccField | SFXMailMessage::GetField

Argument

Return value

Return the body of the mail message.

Return null in case of the multi-part message.

Description

To get the body of multi-part message, use the SFXMailMessage::GetMultipartMessage function.

Reference

SFXMailMessage::SetBody | SFXMailMessage::GetMultipartMessage | SFXMailMessage::GetBodyText

Return value

Return the reference to the body of this mail message.

Return a reference to the "null" string in case of the multi-part message.

Description

To deal with the body of this mail message efficiently, use the SFXMailMessage::GetBodyRef function.

Reference

SFXMailMessage::SetBody | SFXMailMessage::GetBody | SFXMailMessage::GetBodyText

Argument

Return value

Return the body of this mail message.

In case of the multi-part message, the first text of the multi-part part is returned.

Reference

SFXMailMessage::SetBody | SFXMailMessage::GetMultipartMessage | SFXMailMessage::GetBody

Argument

Return value

Return the value of Cc field.

Reference

SFXMailMessage::AddCcField | SFXMailMessage::ReplaceCcField | SFXMailMessage::GetField

Return value

Reference

SFXMailMessage::SetContentType

Return value

Return the value of the Date field(SFXDate).

Reference

SFXMailUtility::ParseDate | SFXDate

Argument

Return value

Return the Epilogue (suffix part) of the multi-part message.

Return null if there is no Epilogue (suffix part) in the multi-part message.

Description

Epilogue (suffix part) is a string added at the end of the multi-part message defined in RFC2046 (MIME Part Two : Media Types Text).

Reference

SFXMailMessage::SetEpilogue | SFXMailMessage::GetPreamble | SFXMailMessage::SetPreamble | SFXMailMessage::IsMultipart

Argument

Return value

Return the value of the specified field.

Description

If more than one value are stored with the same field name, only the first value is read.

To get all the values stored with the same field name, use the SFXMailMessage::GetFieldList function.

Reference

SFXMailMessage::AddField | SFXMailMessage::ReplaceField | SFXMailMessage::HasField | SFXMailMessage::RemoveField | SFXMailMessage::GetFieldList

Return value

Return all the header fields of this mail message as the instance of the SFXProperty class.

Description

	Please edit the header of this mail message carefully!
	The validity of the field names will not be checked when editing the header of this mail message using the SFXProperty instance obtained by the SFXMailMessage::GetFieldList function. Therefore, you need to note the following items. Only the alphabets and hyphen can be used for the field name. The field name is case-insensitive, not case-sensitive.

Reference

SFXMailMessage::AddField | SFXMailMessage::ReplaceField | SFXMailMessage::RemoveField | SFXMailMessage::HasField | SFXMailMessage::RemoveField | SFXMailMessage::GetField | SFXProperty

Argument

Return value

Return From field value.

Reference

SFXMailMessage::SetFromField | SFXMailMessage::GetField

Return value

Return a pointer to the internal message in the multi-part message(SFXMailMessage instance).

Description

The multi-part message has multiple of internal messages as the SFXMailMessage instances.

The pointer to any internal message can be obtained by specifying its "index" number(The "index" number starts from 0).

If the mail message is not a multi-part message, or the "index" number is out of range, "null" is returned.

Example

Get the internal messages in the multi-part message one by one.

// "msg" has mail message
SInt32 i;
SFXMailMessage msg;
SFXMailMessagePtr mail;

if (msg.IsMultipart()) { //check whether or not the mail message is multi-part
    for (i = 0; i < msg.GetMultipartSize(); i++) {
        mail = msg.GetMultipartMessage(i);
        // process mail
        ...
    }
}

Reference

SFXMailMessage::IsMultipart | SFXMailMessage::AddMultipartBody | SFXMailMessage::GetMultipartMessage

Return value

Return the number of internal messages in the multi-part message.

Return 0 if the message has no multi-part.

Reference

SFXMailMessage::GetMultipartMessage | SFXMailMessage::GetAttachedFile

Argument

Return value

Return the Preamble (prefix part) of the multi-part message.

Return null if there is no Preamble (prefix part) in the multi-part message.

Description

The Preamble(prefix part) is a string added at the beginning of the multi-part message defined in RFC2046 ( MIME Part Two : Media Types Text ).

The string such as "This is a MIME multipart message." is set.

Reference

SFXMailMessage::SetPreamble | SFXMailMessage::GetEpilogue | SFXMailMessage::SetEpilogue | SFXMailMessage::IsMultipart

Argument

Return value

Return the value of Subject field.

Description

	Encoding of the Subject field
	RFC2231(MIME Parameter Value and Encoded Word Extensions) is not supported.

Reference

SFXMailMessage::SetSubjectField | SFXMailMessage::GetField

Argument

Return value

Return the value of the To field.

Reference

SFXMailMessage::AddToField | SFXMailMessage::ReplaceToField | SFXMailMessage::GetField

Argument

Return value

Reference

SFXMailMessage::AddField | SFXMailMessage::ReplaceField | SFXMailMessage::RemoveField | SFXMailMessage::GetField | SFXMailMessage::GetFieldList

Return value

Description

If the mainType of the Content-Type is "multipart", it is a multi-part message.

Reference

SFXMailMessage::SetContentType

Argument

Return value

Description

This function can be used for the multi-part message.

Reference

SFXMailMessage::Write | SFXMailMessage::ParseHeaderOnly

Argument

Return value

Reference

SFXMailMessage::Write | SFXMailMessage::Parse

Description

The SFXMailMessage::RemoveField function does nothing if the specified field does not exist.

Reference

SFXMailMessage::ReplaceToField | SFXMailMessage::ReplaceCcField | SFXMailMessage::ReplaceBccField | SFXMailMessage::AddField | SFXMailMessage::HasField | SFXMailMessage::RemoveField | SFXMailMessage::GetField | SFXMailMessage::GetFieldList

Argument

Return value

Reference

SFXMailMessage::AddBccField | SFXMailMessage::GetBccField | SFXMailMessage::ReplaceField

Argument

Return value

Reference

SFXMailMessage::AddCcField | SFXMailMessage::GetCcField | SFXMailMessage::ReplaceField

Argument

Return value

Description

If the specified field does not exist, it will be created with the specified value.

If the number of fields with the specified name is one, its value will be replaced with the specified value.

If the number of fields with the specified name is more than one, only the value of first field will be replaced with the specified value.

Reference

SFXMailMessage::AddField | SFXMailMessage::HasField | SFXMailMessage::RemoveField | SFXMailMessage::GetField | SFXMailMessage::GetFieldList

Argument

Return value

Reference

SFXMailMessage::AddToField | SFXMailMessage::GetToField | SFXMailMessage::ReplaceField

Argument

Return value

Description

	Multi-part message
	This function fails in case of the multi-part message. To add the Body to the multi-part message, create a instance of the SFXMailMessage class, set the Body to this instance, and add this instance to the multi-part message using the SFXMailMessage::AddMultipartBody function.

Reference

SFXMailMessage::GetBody | SFXMailMessage::AddMultipartBody | SFXMailMessage::IsMultipart

Return value

Description

If mainType is "multipart", the mail message is processed as a multi-part message.

Reference

SFXMailMessage::GetContentType | SFXMailMessage::IsMultipart

Return value

Description

Epilogue(suffix part) is a string added at the end of the multi-part message defined in RFC2046 (MIME Part Two : Media Types Text).

This setting is invalid if the message has no multi-part.

Reference

SFXMailMessage::GetEpilogue | SFXMailMessage::SetPreamble | SFXMailMessage::IsMultipart

Argument

Return value

Reference

SFXMailMessage::GetFromField | SFXMailMessage::ReplaceField

Return value

Description

Preamble (prefix part) is a string added at the beginning of the multi-part message defined in RFC2046 (MIME Part Two : Media Types Text).

A string such as "This is a MIME multi-part message." is set.

This setting is invalid if the message has no multi-part.

Reference

SFXMailMessage::GetPreamble | SFXMailMessage::SetEpilogue | SFXMailMessage::IsMultipart

Argument

Return value

Reference

SFXMailMessage::GetSubjectField | SFXMailMessage::ReplaceField

Argument

Return value

Return the mail message as text.

Description

The mail message is written as a text. If "true" is set to the isEncode argument, it is automatically converted into a appropriate character-code for sending mail.

Description

	Encoding of the Subject field and the file name of attached data
	RFC2231(MIME Parameter Value and Encoded Word Extensions) is not supported.

Reference

SFXMailMessage::Parse