mail::Attachment
Prev | Extra/Miscellaneous objects/methods | Next

## Name

mail::Attachment — Create MIME content.

## Synopsis

#include <libmail/attachments.H>

## USAGE

The mail::Attachment class formats a wide variety of MIME messages from raw content. Most of the functionality in this class is provided by the constructors. mail::Attachment provides a variety of constructors for creating content MIME entities, and multipart MIME entities.

### Creating content MIME entities

`fsfuncmail::Attachment(` | std::string headers,
| int content_fd`)`;

`fsfuncmail::Attachment(` | std::string headers,
| int content_fd,
| std::string charset,
| std::string transfer_encoding=""`)`;

`fsfuncmail::Attachment(` | std::string headers,
| std::string content_str`)`;

`fsfuncmail::Attachment(` | std::string headers,
| std::string content_str,
| std::string charset,
| std::string transfer_encoding=""`)`;

A non-multipart entity is created by providing the content in a file descriptor (`content_fd`) or explicitly (`content_str`).

### Note

The mail::Attachment object makes an internal copy of the file descriptor. The original file descriptor does not need to remain open after the mail::Attachment object is constructed. The duplicate file descriptor will be closed automatically when the object is destroyed.

The headers of the MIME entity are provided explicitly. The first argument to the constructor (`headers`) is usually an initialized mail::Header::list(3x) object. It's `std::string` operator will conveniently generate a well-formed list of mail headers.

The `charset` and `transfer_encoding` parameters are optional. `content_fd` or `content_str` provides the raw, unencoded, data for the MIME object. The mail::Attachment object will heuristically select the most appropriate MIME encoding if the `charset` and `transfer_encoding` parameters are not provided.

The data may be either plain text, or binary data. mail::Attachment will determine it automatically. The optional `charset` parameter specifies the plain text's character set. If specified, it will be factored into mail::Attachment's heuristic selection of the most appropriate MIME encoding for this plain text content. Finally, specifying `transfer_encoding` will override mail::Attachment's heuristics, and forcibly set the MIME encoding accordingly.

### Note

To specify the MIME encoding only, specify an empty string for `charset` (this would be appropriate for setting the MIME encoding - which will obviously be `base64` here - for binary content that is not associated with any character set.

`headers` must include the `Content-Type` header, but must not contain the `Content-Transfer-Encoding` header, which will be provided by the mail::Attachment class.

### Pre-formatted MIME content

It is possible to set `content_fd` or `content_str` to something that's already MIME-formatted. mail::Attachment will conclude that the content is already MIME-formatted when `headers` already contain a `Content-Transfer-Encoding` header, or a `Content-Type` header that sets the MIME type to either “message/rfc822” or any “multipart” MIME type.

This is often used when the content is an existing, well-formed MIME message. Providing a “Content-Type: message/rfc822” in `headers` creates an attached MIME message. This is just one of the two ways to create an attached MIME message. A better way to create an attached MIME message is described later.

### Note

A “multipart” `Content-Type` header must have a “boundary” parameter that actually matches the the MIME boundary delimiter in the specified content.

### Creating multipart MIME content

A multipart MIME content is constructed by creating mail::Attachment for each content MIME section, then using the following multipart constructors:

`fsfuncmail::Attachment(` | std::string headers,
| const std::vector<mail::Attachment *> &parts`)`;

`fsfuncmail::Attachment(` | std::string headers,
| const std::vector<mail::Attachment *> &parts,
| std::string multipart_type,
| const mail::mimestruct::parameterList &multipart_parameters`)`;

The headers of a multipart MIME section must include a well-formed `Content-Type` header set to either “message/rfc822” or “multipart/`subtype`”. Alternatively, mail::Attachment will supply a `Content-Type` header when provided with `multipart_type` and `multipart_parameters`.

### Note

`parts` must be a vector of exactly one element when `multipart_type` (or an existing `Content-Type` header) is “message/rfc822”).

### Generating MIME-formatted messages

mail::Attachment top_attachment;
std::string buffer;
bool errflag;
top_attachment->begin();
while ((buffer=top_attachment->generate(errflag)).size() > 0)
{
std::cout << buffer;
}

Once all mail::Attachment objects are created, the MIME-formatted message is generated by first calling the `begin`() method of the topmost mail::Attachment object, then repeatedly calling the `generate`() method until it returns an empty string. Each call to `generate`() returns the next portion of the formatted MIME message, and the empty string is returned after the entire MIME message is produced. All mail::Attachment objects must be destroyed immediately afterwards.

A `false` `errflag`, when `generate`() returns an empty string, indicates that the MIME-formatted message was generated succesfully. A `true` `errflag` indicated an `errno`-related failure to generate the MIME-formatted message.

### Note

`generate`() will supply the “Mime-Version: 1.0” header. This header does not need to be explicitly included in the `headers` of the topmost mail::Attachment object.

## SEE ALSO

mail::Header::addresslist(3x), mail::Header::encoded(3x), mail::Header::mime(3x), mail::Header::plain(3x).

Prev | Up | Next
mail::address | Home | ToC | mail::emailAddress