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.
mail::Attachment
(std::string headers, int content_fd);
mail::Attachment
(std::string headers, int content_fd, std::string charset, std::string transfer_encoding="");
mail::Attachment
(std::string headers, std::string content_str);
mail::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 |
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.
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. |
A multipart MIME content is constructed by creating
mail::Attachment
for each content MIME section,
then using the following multipart constructors:
mail::Attachment
(std::string headers, const std::vector<mail::Attachment *> &parts);
mail::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"). |
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::Header::addresslist(3x), mail::Header::encoded(3x), mail::Header::mime(3x), mail::Header::plain(3x).
<<< Previous | Home | Next >>> |
mail::address | Up | mail::emailAddress |