mail::Attachment — Create MIME content.
#include <libmail/attachments.H>
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
).
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.
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.
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
.
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.
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.