1 Cone©
2MAIL::ATTACHMENT(3x) Cone: COnsole Newsreader And E MAIL::ATTACHMENT(3x)
4
8 mail::Attachment - Create MIME content.
9
11 #include <libmail/attachments.H>
12
14 The mail::Attachment class formats a wide variety of MIME messages from
15 raw content. Most of the functionality in this class is provided by the
16 constructors. mail::Attachment provides a variety of constructors for
17 creating content MIME entities, and multipart MIME entities.
18 Creating content MIME entities
20 mail::Attachment(std::string headers, int content_fd);
21 mail::Attachment(std::string headers, int content_fd,
23 std::string 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
34 The mail::Attachment object makes an internal copy of the file
35 descriptor. The original file descriptor does not need to remain
36 open after the mail::Attachment object is constructed. The
37 duplicate file descriptor will be closed automatically when the
38 object is destroyed.
39 The headers of the MIME entity are provided explicitly. The first
41 argument to the constructor (headers) is usually an initialized
42 mail::Header::list(3x) object. It's std::string operator will
43 conveniently generate a well-formed list of mail headers.
44 The charset and transfer_encoding parameters are optional. content_fd
46 or content_str provides the raw, unencoded, data for the MIME object.
47 The mail::Attachment object will heuristically select the most
48 appropriate MIME encoding if the charset and transfer_encoding
49 parameters are not provided.
50 The data may be either plain text, or binary data. mail::Attachment
52 will determine it automatically. The optional charset parameter
53 specifies the plain text's character set. If specified, it will be
54 factored into mail::Attachment's heuristic selection of the most
55 appropriate MIME encoding for this plain text content. Finally,
56 specifying transfer_encoding will override mail::Attachment's
57 heuristics, and forcibly set the MIME encoding accordingly.
58 Note
60 To specify the MIME encoding only, specify an empty string for
61 charset (this would be appropriate for setting the MIME encoding -
62 which will obviously be base64 here - for binary content that is
63 not associated with any character set.
64 headers must include the Content-Type header, but must not contain the
66 Content-Transfer-Encoding header, which will be provided by the
67 mail::Attachment class.
68 Pre-formatted MIME content
70 It is possible to set content_fd or content_str to something that's
71 already MIME-formatted. mail::Attachment will conclude that the
72 content is already MIME-formatted when headers already contain a
73 Content-Transfer-Encoding header, or a Content-Type header that sets
74 the MIME type to either “message/rfc822” or any “multipart” MIME type.
75 This is often used when the content is an existing, well-formed MIME
77 message. Providing a “Content-Type: message/rfc822” in headers creates
78 an attached MIME message. This is just one of the two ways to create an
79 attached MIME message. A better way to create an attached MIME message
80 is described later.
81 Note
83 A “multipart”Content-Type header must have a “boundary” parameter
84 that actually matches the the MIME boundary delimiter in the
85 specified content.
86 Creating multipart MIME content
88 A multipart MIME content is constructed by creating mail::Attachment
89 for each content MIME section, then using the following multipart
90 constructors:
91 mail::Attachment(std::string headers,
93 const std::vector<mail::Attachment *> &parts);
94 mail::Attachment(std::string headers,
96 const std::vector<mail::Attachment *> &parts,
97 std::string multipart_type,
98 const mail::mimestruct::parameterList &multipart_parameters);
99 The headers of a multipart MIME section must include a well-formed
101 Content-Type header set to either “message/rfc822” or
102 “multipart/subtype”. Alternatively, mail::Attachment will supply a
103 Content-Type header when provided with multipart_type and
104 multipart_parameters.
105 Note
107 parts must be a vector of exactly one element when multipart_type
108 (or an existing Content-Type header) is “message/rfc822”).
109 Generating MIME-formatted messages
111 mail::Attachment top_attachment;
112 std::string buffer;
113 bool errflag;
114 top_attachment->begin();
116 while ((buffer=top_attachment->generate(errflag)).size() > 0)
117 {
118 std::cout << buffer;
119 }
120 Once all mail::Attachment objects are created, the MIME-formatted
122 message is generated by first calling the begin() method of the topmost
123 mail::Attachment object, then repeatedly calling the generate() method
124 until it returns an empty string. Each call to generate() returns the
125 next portion of the formatted MIME message, and the empty string is
126 returned after the entire MIME message is produced. All
127 mail::Attachment objects must be destroyed immediately afterwards.
128 A falseerrflag, when generate() returns an empty string, indicates that
130 the MIME-formatted message was generated succesfully. A trueerrflag
131 indicated an errno-related failure to generate the MIME-formatted
132 message.
133 Note
135 generate() will supply the “Mime-Version: 1.0” header. This header
136 does not need to be explicitly included in the headers of the
137 topmost mail::Attachment object.
138
140 mail::Header::addresslist(3x), mail::Header::encoded(3x),
141 mail::Header::mime(3x), mail::Header::plain(3x).
142
144 Sam Varshavchik
145Cone© 08/25/2016 MAIL::ATTACHMENT(3x)