1        Cone©
2
3MAIL::ATTACHMENT(3x)    Cone: COnsole Newsreader And E    MAIL::ATTACHMENT(3x)
4
5
6

NAME

8       mail::Attachment - Create MIME content.
9

SYNOPSIS

11       #include <libmail/attachments.H>
12

USAGE

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
19   Creating content MIME entities
20       mail::Attachment(std::string headers, int content_fd);
21
22       mail::Attachment(std::string headers, int content_fd,
23                        std::string charset, std::string transfer_encoding=");
24
25       mail::Attachment(std::string headers, std::string content_str);
26
27       mail::Attachment(std::string headers, std::string content_str,
28                        std::string charset, std::string transfer_encoding=");
29
30       A non-multipart entity is created by providing the content in a file
31       descriptor (content_fd) or explicitly (content_str).
32
33           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
40       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
45       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
51       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
59           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
65       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
69   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
76       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
82           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
87   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
92       mail::Attachment(std::string headers,
93                        const std::vector<mail::Attachment *> &parts);
94
95       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
100       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
106           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
110   Generating MIME-formatted messages
111           mail::Attachment top_attachment;
112           std::string buffer;
113           bool errflag;
114
115              top_attachment->begin();
116              while ((buffer=top_attachment->generate(errflag)).size() > 0)
117              {
118                  std::cout << buffer;
119              }
120
121       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
129       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
134           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

SEE ALSO

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

AUTHOR

144       Sam Varshavchik
145
146
147
148Cone©                             08/25/2016              MAIL::ATTACHMENT(3x)
Impressum