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.

Procedure to send a SMTP mail.

class MyClass {
private:
    SFXSMTPSender _sender;
    CALLBACK_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("fromaddress@example.com");

    // add To address to mail header
    message.AddToField("toaddress1@example.com");
    message.AddToField("toaddress2@example.com");
    
    // add Cc address to mail header
    message.AddCcField("toaddress3@example.com");
    
    // add Bcc address to mail header
    message.AddBccField("toaddress4@example.com");
    
    // 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 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) {
        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 <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>\r\n
SFXAnsiString toString = message.GetToField();

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

// get Date field from mail header as instance of SFXDate class
SFXDate date = message.GetDateField();

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

Reference

SFXMailUtility | SFXMailField

Member

Description

The SFXMailMessage class instance is destroyed. All sub-documents maintained internally are deleted.

Argument

Return value

Reference

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

Argument

Return value

Reference

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

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::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::ReplaceField | SFXMailMessage::HasField | SFXMailMessage::GetField | SFXMailMessage::GetFieldList

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

Argument

Return value

Description

The file encoded in the Base64 format is automaticaly decoded.

Reference

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

Argument

Return value

Return the value of the Bcc field.

Reference

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

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 the mail message.

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

Description

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

Reference

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

Argument

Return value

Return the body of the 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 the Cc field.

Reference

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

Return value

Reference

SFXMailMessage::SetContentType

Return value

Return the value of the Date field in the SFXDate format.

Reference

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

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 a 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::GetFieldList | SFXMailMessage::HasField

Return value

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

Description

	Please edit the header of the mail message carefully!
	The validity of the field names will not be checked when editing the header of the 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::GetField | SFXMailMessage::HasField | SFXProperty

Argument

Return value

Return From field value.

Reference

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

Return value

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

Description

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

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 the 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 the Subject field.

Reference

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

Argument

Return value

Return the value of the To field.

Reference

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

Argument

Return value

Reference

SFXMailMessage::AddField | SFXMailMessage::ReplaceField | 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

The SFXMailMessage::Parse 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.

Argument

Return value

Reference

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

Argument

Return value

Reference

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

Argument

Return value

Description

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

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

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

Reference

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

Argument

Return value

Reference

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

Argument

Return value

Description

	Multi-part message
	The SFXMailMessage::SetBody 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::GetPreamble | SFXMailMessage::SetPreamble | SFXMailMessage::IsMultipart

Argument

Return value

Reference

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

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::GetEpilogue | SFXMailMessage::SetEpilogue | SFXMailMessage::IsMultipart

Argument

Return value

Reference

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

Argument

Return value

Return the mail message as text.

Description

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

Reference

SFXMailMessage::Parse