BMailMessage

Derived from: none
Declared in:  be/mail/E-mail.h
Library: libmail.so
Summary:  more...

The BMailMessage class provides an easy way to send e-mail messages. If you want to do it the hard way, look up the SMTP RFC and start plodding your way through the Network Kit documentation. You'll get it working one of these days.

Or you can sail right on through and be sending e-mail from your own applications in a matter of minutes using your friend, the BMailMessage.

Constructing a Mail Message

To send an e-mail, you simply construct a new BMailMessage object, add a "To" header field, add the content, and send the message on its way. For example:

BMailMessage *mail; char *message; mail = new BMailMessage(); mail->AddHeaderField(B_MAIL_TO, "bob@uncle.com"); mail->AddHeaderField(B_MAIL_SUBJECT, "Hi"); message = "Hi, Uncle Bob!"; mail->AddContent(message, strlen(message));

This is a pretty basic message. The subject is "Hi," the message is sent to "bob@uncle.com," and the message body is "Hi, Uncle Bob!"

You can add other fields, including carbon-copy (CC) and blind-carbon-copy (BCC) fields, and you can add attachments. For example, if you want to also attach a file called "/boot/home/file.zip," you can do the following:

mail->AddEnclosure("/boot/home/file.zip");

Once your message has been constructed, you can send it by calling Send():

mail->Send();

That's the basic technique behind sending e-mail under the BeOS. The mail daemon also fetches incoming mail from a POP server, but you can't use the BMailMessage class to read these messages; you use the BeOS BQuery and BNode classes to locate messages of interest and obtain information about them. See "Querying Mail Messages" for more information.

Constructor and Destructor

BMailMessage()

BMailMessage(void)

Creates and returns a new BMailMessage object, which is empty. You need to call other functions defined by this class to fill out the message.

~BMailMessage()

~BMailMessage()

Destroys the BMailMessage, even if the object's fields are "dirty." For example, if you create a new BMailMessage object with the intention of sending a message, fill out some or all of the fields, and then delete the object, the object is destroyed without being sent.

Member Functions

AddContent()

status_t AddContent(const char *text,       int32 length,       uint32 encoding = B_ISO1_CONVERSION,       bool replace = false) status_t AddContent(const char *text,       int32 length,       const char *encoding,       bool replace = false)

Adds the specified text (which contains length characters) to the BMailMessage object's content. The text's encoding is specified by the encoding parameter, either directly or by pointer.

If replace is true, any existing text is deleted before the new content is added; otherwise, the specified text is appended to the end of the existing message content.

RETURN CODES

• B_OK. The content was changed without error.

• B_ERROR. Unable to add the new content.

AddEnclosure()

status_t AddEnclosure(entry_ref *enclosure_ref, bool replace = false) status_t AddEnclosure(const char *path, bool replace = false) status_t AddEnclosure(const char *mime_type,       void *data,       int32 length,       bool replace = false)

Adds an attachment to the message. The first two forms of AddEnclosure() add a file to the message, given either an entry_ref pointer or a pathname. The third form adds a block of memory (of the given length) to the message as an enclosure, with the specified MIME type.

If replace is true, any existing attachments—including the body of the message—are removed before the new one is added; otherwise the new enclosure is added, leaving previous attachments intact.

If you specify true for replace, not only will all existing enclosures be discarded, but so will the content of the message body itself.

RETURN CODES

• B_OK. The content was changed without error.

• B_ERROR. Unable to add the new enclosure.

AddHeaderField()

status_t AddHeaderField(const char *field_name,       const char *field_str,       bool replace = false)

Adds a header field to the BMailMessage object. The value of the field whose name is specified by field_name is set to the string specified by field_str.

If replace is true, all existing header fields of the specified name are deleted before adding the new header field; if replace is false, a new header whose field is named field_name is added.

RETURN CODES

• B_OK. The content was changed without error.

• B_ERROR. Unable to add the new header field.

Send()

status_t Send(bool send_now = false, bool remove_when_sent = false)

Queues the message for transmission. If send_now is true, the message is sent immediately; otherwise, it is placed in the queue to be sent the next time check_for_mail() is called or the mail daemon performs an automatic mail check.

If the remove_when_sent argument is true, the message will be deleted from the user's disk drive after it has been sent; otherwise, it will be saved for posterity.

RETURN CODES

• B_OK. The content was changed without error.

• B_MAIL_NO_RECIPIENT. There needs to be either a "To" or "Bcc" field in the message.

• Errors from BMessage::SendMessage().