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