mail::Attachment(3x)

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

NAME

6       mail::Attachment - Create MIME content.
7

SYNOPSIS

9       #include <libmail/attachments.H>
10

USAGE

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 the
14       constructors.  mail::Attachment provides a variety of constructors for
15       creating content MIME entities, and multipart MIME entities.
16
17   Creating content MIME entities
18       mail::Attachment(std::string headers, int content_fd);
19
20       mail::Attachment(std::string headers, int content_fd,
21                        std::string charset, std::string transfer_encoding=");
22
23       mail::Attachment(std::string headers, std::string content_str);
24
25       mail::Attachment(std::string headers, std::string content_str,
26                        std::string charset, std::string transfer_encoding=");
27
28       A non-multipart entity is created by providing the content in a file
29       descriptor (content_fd) or explicitly (content_str).
30
31           Note
32           The mail::Attachment object makes an internal copy of the file
33           descriptor. The original file descriptor does not need to remain
34           open after the mail::Attachment object is constructed. The
35           duplicate file descriptor will be closed automatically when the
36           object is destroyed.
37
38       The headers of the MIME entity are provided explicitly. The first
39       argument to the constructor (headers) is usually an initialized
40       mail::Header::list(3x) object. It´s std::string operator will
41       conveniently generate a well-formed list of mail headers.
42
43       The charset and transfer_encoding parameters are optional.  content_fd
44       or content_str provides the raw, unencoded, data for the MIME object.
45       The mail::Attachment object will heuristically select the most
46       appropriate MIME encoding if the charset and transfer_encoding
47       parameters are not provided.
48
49       The data may be either plain text, or binary data.  mail::Attachment
50       will determine it automatically. The optional charset parameter
51       specifies the plain text´s character set. If specified, it will be
52       factored into mail::Attachment´s heuristic selection of the most
53       appropriate MIME encoding for this plain text content. Finally,
54       specifying transfer_encoding will override mail::Attachment´s
55       heuristics, and forcibly set the MIME encoding accordingly.
56
57           Note
58           To specify the MIME encoding only, specify an empty string for
59           charset (this would be appropriate for setting the MIME encoding -
60           which will obviously be base64 here - for binary content that is
61           not associated with any character set.
62
63       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
67   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
70       content is already MIME-formatted when headers already contain a
71       Content-Transfer-Encoding header, or a Content-Type header that sets
72       the MIME type to either “message/rfc822” or any “multipart” MIME type.
73
74       This is often used when the content is an existing, well-formed MIME
75       message. Providing a “Content-Type: message/rfc822” in headers creates
76       an attached MIME message. This is just one of the two ways to create an
77       attached MIME message. A better way to create an attached MIME message
78       is described later.
79
80           Note
81           A “multipart” Content-Type header must have a “boundary” parameter
82           that actually matches the the MIME boundary delimiter in the
83           specified content.
84
85   Creating multipart MIME content
86       A multipart MIME content is constructed by creating mail::Attachment
87       for each content MIME section, then using the following multipart
88       constructors:
89
90       mail::Attachment(std::string headers,
91                        const std::vector<mail::Attachment *> &parts);
92
93       mail::Attachment(std::string headers,
94                        const std::vector<mail::Attachment *> &parts,
95                        std::string multipart_type,
96                        const mail::mimestruct::parameterList &multipart_parameters);
97
98       The headers of a multipart MIME section must include a well-formed
99       Content-Type header set to either “message/rfc822” or
100       “multipart/subtype”. Alternatively, mail::Attachment will supply a
101       Content-Type header when provided with multipart_type and
102       multipart_parameters.
103
104           Note
105           parts must be a vector of exactly one element when multipart_type
106           (or an existing Content-Type header) is “message/rfc822”).
107
108   Generating MIME-formatted messages
109           mail::Attachment top_attachment;
110           std::string buffer;
111           bool errflag;
112
113              top_attachment->begin();
114              while ((buffer=top_attachment->generate(errflag)).size() > 0)
115              {
116                  std::cout << buffer;
117              }
118
119       Once all mail::Attachment objects are created, the MIME-formatted
120       message is generated by first calling the begin() method of the topmost
121       mail::Attachment object, then repeatedly calling the generate() method
122       until it returns an empty string. Each call to generate() returns the
123       next portion of the formatted MIME message, and the empty string is
124       returned after the entire MIME message is produced. All
125       mail::Attachment objects must be destroyed immediately afterwards.
126
127       A false errflag, when generate() returns an empty string, indicates
128       that the MIME-formatted message was generated succesfully. A true
129       errflag indicated an errno-related failure to generate the
130       MIME-formatted message.
131
132           Note
133           generate() will supply the “Mime-Version: 1.0” header. This header
134           does not need to be explicitly included in the headers of the
135           topmost mail::Attachment object.
136

NAME

SYNOPSIS

USAGE

SEE ALSO