1mail::Attachment(3x) Extra/Miscellaneous objects/methods mail::Attachment(3x)
2
6 mail::Attachment - Create MIME content.
7
9 #include <libmail/attachments.H>
10
12 The mail::Attachment class formats a wide variety of MIME messages from
13 raw content. Most of the functionality in this class is provided by
14 the constructors. mail::Attachment provides a variety of constructors
15 for creating content MIME entities, and multipart MIME entities.
16 CREATING CONTENT MIME ENTITIES
18 mail::Attachment (std::string headers, int content_fd);
21 mail::Attachment (std::string headers, int content_fd, std::string
23 charset, std::string transfer_encoding="");
24 mail::Attachment (std::string headers, std::string content_str);
26 mail::Attachment (std::string headers, std::string content_str,
28 std::string charset, std::string transfer_encoding="");
29 A non-multipart entity is created by providing the content in a file
31 descriptor (content_fd) or explicitly (content_str).
32 Note: The mail::Attachment object makes an internal copy of the
34 file descriptor. The original file descriptor does not need to
35 remain open after the mail::Attachment object is constructed.
36 The duplicate file descriptor will be closed automatically when
37 the object is destroyed.
38 The headers of the MIME entity are provided explicitly. The first
40 argument to the constructor (headers) is usually an initialized
41 mail::Header::list(3x) object. It's std::string operator will conve‐
42 niently generate a well-formed list of mail headers.
43 The charset and transfer_encoding parameters are optional. content_fd
45 or content_str provides the raw, unencoded, data for the MIME object.
46 The mail::Attachment object will heuristically select the most appro‐
47 priate MIME encoding if the charset and transfer_encoding parameters
48 are not provided.
49 The data may be either plain text, or binary data. mail::Attachment
51 will determine it automatically. The optional charset parameter speci‐
52 fies the plain text's character set. If specified, it will be factored
53 into mail::Attachment's heuristic selection of the most appropriate
54 MIME encoding for this plain text content. Finally, specifying trans‐
55 fer_encoding will override mail::Attachment's heuristics, and forcibly
56 set the MIME encoding accordingly.
57 Note: To specify the MIME encoding only, specify an empty string
59 for charset (this would be appropriate for setting the MIME
60 encoding - which will obviously be base64 here - for binary con‐
61 tent that is not associated with any character set.
62 headers must include the Content-Type header, but must not contain the
64 Content-Transfer-Encoding header, which will be provided by the
65 mail::Attachment class.
66 PRE-FORMATTED MIME CONTENT
68 It is possible to set content_fd or content_str to something that's
69 already MIME-formatted. mail::Attachment will conclude that the con‐
70 tent is already MIME-formatted when headers already contain a Content-
71 Transfer-Encoding header, or a Content-Type header that sets the MIME
72 type to either ``message/rfc822'' or any ``multipart'' MIME type.
73 This is often used when the content is an existing, well-formed MIME
75 message. Providing a ``Content-Type: message/rfc822'' in headers cre‐
76 ates an attached MIME message. This is just one of the two ways to
77 create an attached MIME message. A better way to create an attached
78 MIME message is described later.
79 Note: A ``multipart'' Content-Type header must have a ``bound‐
81 ary'' parameter that actually matches the the MIME boundary
82 delimiter in the specified content.
83 CREATING MULTIPART MIME CONTENT
85 A multipart MIME content is constructed by creating mail::Attachment
86 for each content MIME section, then using the following multipart con‐
87 structors:
88 mail::Attachment (std::string headers, const std::vector<mail::Attach‐
92 ment *> &parts);
93 mail::Attachment (std::string headers, const std::vector<mail::Attach‐
95 ment *> &parts, std::string multipart_type, const
96 mail::mimestruct::parameterList &multipart_parameters);
97 The headers of a multipart MIME section must include a well-formed Con‐
99 tent-Type header set to either ``message/rfc822'' or ``multipart/sub‐
100 type''. Alternatively, mail::Attachment will supply a Content-Type
101 header when provided with multipart_type and multipart_parameters.
102 Note: parts must be a vector of exactly one element when multi‐
104 part_type (or an existing Content-Type header) is ``mes‐
105 sage/rfc822'').
106 GENERATING MIME-FORMATTED MESSAGES
108 mail::Attachment top_attachment;
109 std::string buffer;
110 bool errflag;
111 top_attachment->begin();
113 while ((buffer=top_attachment->generate(errflag)).size() > 0)
114 {
115 std::cout << buffer;
116 }
117 Once all mail::Attachment objects are created, the MIME-formatted mes‐
119 sage is generated by first calling the begin() method of the topmost
120 mail::Attachment object, then repeatedly calling the generate() method
121 until it returns an empty string. Each call to generate() returns the
122 next portion of the formatted MIME message, and the empty string is
123 returned after the entire MIME message is produced. All mail::Attach‐
124 ment objects must be destroyed immediately afterwards.
125 A false errflag, when generate() returns an empty string, indicates
127 that the MIME-formatted message was generated succesfully. A true
128 errflag indicated an errno-related failure to generate the MIME-format‐
129 ted message.
130 Note: generate() will supply the ``Mime-Version: 1.0'' header.
132 This header does not need to be explicitly included in the head‐
133 ers of the topmost mail::Attachment object.
134
136 mail::Header::addresslist(3x), mail::Header::encoded(3x),
137 mail::Header::mime(3x), mail::Header::plain(3x).
138 10 April 2006 mail::Attachment(3x)