Mail Kit 2 Root | The Public API

# MailMessage

> Derived from: MailComponent
> Declared in: include/public/MailMessage.h
> Library: libmail.so

> MailMessage is what you use if you are interested in actually sending messages. It allows you to add an arbitrary number of components (naturally making it multipart only if there is more than one), and provides many convenience functions for adding, modifying and accessing both headers and data. If you use this kit, you will get to know MailMessage very well.

## C onstructor and D estructor

| MailMessage()

> `MailMessage(` BPositionIO *mail_file = NULL `)`

> Creates a new MailMessage. If mail_file is not NULL, the MailMessage will be instantiated to the RFC 822 format data contained in mail_file.

| ~MailMessage()

> virtual `~MailMessage()`

> Destroys the message, frees internal buffers, and deletes all added components.

## M ember F unctions

| To (), From (), ReplyTo (), CC (), Subject (), Priority ()

> const char * `To()`
> const char * `From()`
> const char * `ReplyTo()`
> const char * `CC()`
> const char * `Subject()`
> int `Priority()`

> Returns the relevant header field from the message. These are simply a convenience. `Subject()`, for instance, is equivalent to, and implemented as, `HeaderField("Subject")`. There is no `BCC()` function because, for obvious reasons, it is impossible to retrieve BCCs from the message.

| SetTo (), SetFrom (), SetReplyTo (), SetCC (), SetBCC (), SetSubject (), SetPriority ()

> void `SetTo(` const char *to `)`
> void `SetFrom(` const char *to `)`
> void `SetReplyTo(` const char *to `)`
> void `SetCC(` const char *to `)`
> void `SetBCC(` const char *to `)`
> void `SetSubject(` const char *to `)`
> void `SetPriority(` int to `)`

> Returns the relevant header field of the message. With the exception of `SetBCC()`, these are simply conveniences which can be easily emulated with SetHeaderField().

| SendViaAccount ()

> void `SendViaAccount(` const char *account_name `)`
> void `SendViaAccount(` int32 chain_id `)`

> Sets the message up so that it is sent via the account specified by either account_name or chain_id, which of course must exist as an outbound chain (see MailChain::ChainDirection() for details). Automatically calls SetFrom() with the return address indicated in the specified chain using the format "Real Name" <e-mail>.

| AddComponent()

> void `AddComponent(` MailComponent *component `)`

> Adds component to this MailMessage. Note that the MailMessage assumes ownership of component. Thus, you may not delete component. If you continue to modify to it after calling `AddComponent()`, your changes will be reflected when you call Render(). `AddComponent()` automatically makes the message multipart if there is more than one component.

| GetComponent()

> MailComponent * `GetComponent(` int32 index `)`

> Returns the component at index. Instantiate()s it if it has not yet been instantiated. Otherwise, returns already instantiated component. Use RTTI or MailComponent hooks to do useful things with the returned component.

| CountComponents()

> int32 `CountComponents()` const

> Returns the total number of components in this MailMessage.

| Attach ()

> void `Attach(` entry_ref *ref, bool include_attributes = true `)`

> Attaches ref to this message. If include_attributes is true, uses an AttributedMailAttachment instead of a SimpleMailAttachment. Be aware that is attached in the state it is in when the message is rendered, not when `Attach()` is called.

| IsComponentAttachment ()

> bool `IsComponentAttachment(` int32 index`)`

> If the component at index is an attachment of any kind, returns true, otherwise returns false.

| SetBodyTextTo ()

> void `SetBodyTextTo(`const char *text`)`

> Sets the body of this message to the UTF8 string contained in text. If no body has been specified through SetBody(), `SetBodyTextTo()` creates one.

| BodyText ()

> const char * `BodyText()`

> Returns the contents of Body() as a UTF8 string. Returns NULL if no body exists.

| SetBody ()

> status_t `SetBody(` PlainTextBodyComponent *body`)`

> Sets the body of this message to body. If a body has already been specified, `SetBody()` returns B_ERROR, otherwise returns B_OK.

| Body ()

> PlainTextBodyComponent * `Body()`

> Returns the body as a PlainTextBodyComponent pointer. Returns NULL if no body exists. This object belongs to the MailMessage, do not delete it.

| Instantiate ()

> virtual status_t `Instantiate(`BPositionIO *data, size_t length`)`

> Initializes this message to the RFC 822 format data in data, starting at data ->Position(), for up to length bytes.

> Return Value:

> > - B_OK if everything succeeds.

> > - B_BAD_TYPE if data does not seem to be an e-mail message.

| Render ()

> virtual status_t `Render(`BPositionIO *data`)`

> Renders the message into RFC 822 format and places the result in data, starting at data ->Position(). If data is a BFile, writes appropriate attributes and sets its MIME type to text/x-email.

> Return Value:

> > - B_OK if everything succeeds.

| RenderTo ()

> status_t `RenderTo(`BDirectory *dir`)`

> Creates a new file in dir, named according to the following format: "Subject" <To> unique indentifier. Calls Render() on the resulting file and writes appropriate attributes.

> Return Value:

> > - B_OK if everything succeeds.

| Send ()

> status_t `Send(`bool send_now`)`

> Calls RenderTo() with the directory specified by the MailChain passed to SendViaAccount(). If that is invalid, it uses the default outbound chain given by MailSettings::DefaultOutboundChainID(). After rendering the message, if send_now is true, calls MailDaemon::SendQueuedMail().

> Return Value:

> > - B_OK if everything succeeds.

> > - B_MAIL_NO_DAEMON if the mail daemon is not running.

> > - something else if there is another error.

Mail Kit 2 Root | The Public API

Mail Daemon 2 API Documentation

©2001 Dr. Zoidberg Enterprises