1 Cone©
2MAIL::FOLDER::ADDMES(3x)Cone: COnsole Newsreader And EMAIL::FOLDER::ADDMES(3x)
4
8 mail::folder::addMessage - Add a message to a folder
9
11 #include <libmail/mail.H>
12 class myCallback : public mail::callback {
15 public:
16 void success(std::string msg);
17 void fail(std::string msg);
18 };
19 #include <libmail/addmessage.H>
21 mail::folder *folder;
23 time_t messageDate;
24 mail::messageInfo newMessageInfo;
25 std::string messageBody;
26 mail::addMessage *msg=folder->addMessage(myCallback &callback);
28 msg->messageDate=messageDate;
30 msg->messageInfo=messageInfo;
31 msg->saveMessageContents(messageBody);
32 if (changedMyMind)
34 msg->fail(std::string errmsg);
35 else
36 msg->go();
37
39 This method begins the process of manually adding a message to a
40 folder. The mail::folder::addMessage method returns a pointer to a
41 mail::addMessage object. The application should then define the
42 contents of the message by invoking the object's saveMessageContents
43 method. The entire contents of the message does not have to be
44 specified at once. A large message may be defined by repeatedly
45 invoking saveMessageContents, consecutively, each time specifying the
46 next portion of the message's contents.
47 After the contents of the message are defined by invoking
49 saveMessageContents, the application must invoke the go method in order
50 to actually place the new message into the folder. The application may
51 abort the process at any time by invoking the fail method, and
52 specifying the error message.
53 The application does not need to explicitly destroy the
55 mail::addMessage object, the object is automatically destroyed by go or
56 fail.
57 The application may set the following mail::addMessage fields prior to
59 invoking go. If not initialized, the following fields will be set to
60 their default values.
61 messageDate
63 The message's timestamp, as retrieved by mail::account::ARRIVALDATE
64 parameter to mail::account::readMessageAttributes(3x)().
65 Note
67 This timestamp does not necessarily have to be the same as the
68 timestamp in the message's Date: header.
69 messageInfo
71 The message flags, as returned by
72 mail::account::getFolderIndexInfo(3x)().
73 Note
75 The contents of uid, the message's unique ID, are ignored, only
76 the message flags in messageInfo are read. The message gets
77 automatically assigned a new unique ID when it gets added to
78 the folder.
79
81 #include <libmail/mail.H>
82 class myCallback : public mail::callback {
85 public:
86 void success(std::string msg);
87 void fail(std::string msg);
88 };
89 mail::addMessage *msg;
91 msg->assembleContent(size_t &handleRet,
93 const mail::Attachment &attachment,
94 mail::callback &cb);
95 msg->assembleMessageRfc822(size_t &handleRet, std::string headers,
97 size_t handle, mail::callback &cb);
98 msg->assembleMultipart(size_t &handleRet, std::string headers,
100 const std::vector<size_t> parts,
101 std::string multipart_type,
102 const mail::mimestruct::parameterList &options,
103 mail::callback &cb);
104 bool flag=msg->assemble(void);
106 This is an alternative way of adding a message to a folder by
108 assembling it one MIME section at a time. First, use the
109 assembleContent method to specify the individual content-containing
110 (non-multipart and non-message/rfc822) MIME sections. Before
111 assembleContent invokes cb's success method it will initialize
112 handleRet with a “handle” that refers to this MIME section. Use these
113 MIME section handles to assemble the individual MIME sections into
114 multipart and message/rfc822 MIME sections. The assembleMessageRfc822
115 and assembleMultipart methods also create a new MIME section handle,
116 which refers to the assembled MIME section, in the same way. Those
117 handles themselves may also be re-assembled into higher-level multipart
118 or message/rfc822 MIME sections.
119 Finally, after defining the topmost MIME section, use assemble to
121 assemble the entire message. If assemble returns true, use the go (or
122 the fail) method. If assemble returns false, an errno-related error has
123 occured; the application should call fail to report it, and clean up
124 the mail::addMessage object.
125 The assembleContent method receives a mail::Attachment(3x) object.
127 The second parameter to assembleMessageRfc822 are the MIME headers of
129 the message/rfc822 attachment. The MIME headers must be terminated by a
130 single newline character, and include the Content-Type header. In
131 nearly all situations, this parameter should be set to the fixed string
132 “Content-Type: message/rfc822\n” (note the trailing newline). The third
133 parameter is the handle of the attachment's top-level MIME section.
134 The second parameter to assembleMultipart is a string containing MIME
136 headers for the multipart MIME section. These headers should not
137 include the Content-Type header. The Content-Type header for the
138 multipart section will be generated internally. If there are any extra
139 headers, they must have a single trailing newline character. Most
140 situations do not need extra headers, so this parameter should be an
141 empty string, “”.
142 The third parameter to assembleMultipart is the vector of
144 previously-defined handles of each MIME section that's to be assembled
145 into a multipart MIME section. The fourth parameter is the actual MIME
146 type of this section, usually “multipart/mixed” or
147 “multipart/alternative” (any “multipart” type is allowed). The fifth
148 parameter is optional, and specifies the MIME content type parameter
149 list (the parameter list should not include the “boundary” parameter,
150 because it's taken care of automatically by this function).
151 The last parameter to assembleContent, assembleMessageRfc822, or
153 assembleMultipart is the callback object. The callback object's success
154 method will be invoked when the MIME section has been assembled. The
155 fail method will be invoked if an error occured. Depending on the type
156 of the folder the message is being added to, the MIME section may be
157 assembled immediately (in which case success or fail gets called right
158 before the function terminates) or the function will terminate
159 immediately, and the callback function will be called at a later time.
160 COPYING ATTACHMENTS FROM OTHER MESSAGES
162 mail::addMessage *msg;
163 msg->assembleImportAttachment(size_t &handleRet, mail::account *acct,
165 std::string uid,
166 const mail::mimestruct &attachment,
167 mail::callback &cb);
168 msg->assembleRemoveAttachmentsFrom(size_t &handleRet,
170 mail::account *acct,
171 std::string uid,
172 const mail::mimestruct &attachment,
173 const std::set &mimeIdList,
174 mail::callback &cb);
175 The assembleImportAttachment function assembles a new MIME section by
177 copying an existing MIME section from another message. acct specifies
178 an open mail account, with an open mail folder. uid specifies the
179 unique identifier of a message in acct's open folder, which can be
180 obtained from mail::account::getFolderIndexInfo(3x). attachment
181 specifies which attachment in message uid should be copied. attachment
182 must be obtained using mail::account::MIMESTRUCTURE with
183 mail::account::readMessageAttributes(3x).
184 Note
186 acct can refer to any open mail account or folder, and does not
187 have to be the same folder the message is being added to!
188 attachment may refer to a multipart, or a non-multipart MIME section.
190 An attachment referring to a multipart MIME section imports the entire
191 multipart MIME section, and all subsections it contains.
192 assembleRemoveAttachmentsFrom also copies the entire multipart MIME
193 section, but skips selected MIME subsections. Any subsection appearing
194 in mimeIdList is not copied. mimeIdList is a list of MIME section
195 identifiers, obtained from mail::mimestruct(3x)'s mime_id field.
196 assembleRemoveAttachmentsFrom implements the “Remove Attachments”
198 function in a typical mail client, which removes individual attachments
199 from a message. To do that, set attachment to the top-level MIME
200 section that refers to the entire message (literally the same object
201 returned by mail::account::readMessageAttributes(3x)) and specify the
202 attachments to remove in mimeIdList. Use mail::folder::addMessage(3x)
203 to add the message to the same folder as the original message (this
204 must be done before invoking assembleRemoveAttachmentsFrom, of course),
205 then when that's done remove the original message.
206
208 mail::addMessage::fail automatically invokes the callback object's fail
209 method, prior to returning. mail::addMessage::go automatically invokes
210 the callback object's success method, when the message is added.
211 mail::addMessage::go will invoke fail if the message cannot be added to
212 the folder, for some reason.
213 Note
215 The mail::folder::addMessage function returns a NULL pointer if the
216 mail::addMessage object cannot be created. This does not
217 necessarily indicate an out-of-memory condition. It is not possible
218 to manually add messages to some types of folders. For example,
219 messages cannot be manually added to POP3 folders, since this is
220 not supported by the POP3 protocol.
221 The callback object's fail method gets invoked just prior to this
223 function returning NULL, in these kinds of situations.
224 The application must wait until callback's success or fail method is
226 invoked. The success method is invoked when this request is succesfully
227 processed. The fail method is invoked if this request cannot be
228 processed. The application must not destroy callback until either the
229 success or fail method is invoked.
230 Note
232 callback's fail method may be invoked even after other callback
233 methods were invoked. This indicates that the request was partially
234 completed before the error was encountered.
235 Note
237 folder does not necessarily have to be a mail::folder object that
238 refers to the currently open folder. Any mail::folder object from
239 an active mail::account object may be used.
240
242 mail::account::getFolderIndexInfo(3x)(),
243 mail::account::readMessageAttributes(3x)().
244
246 Sam Varshavchik
247Cone© 08/25/2016 MAIL::FOLDER::ADDMES(3x)