1        Cone©
2
3MAIL::FOLDER::ADDMES(3x)Cone: COnsole Newsreader And EMAIL::FOLDER::ADDMES(3x)
4
5
6

NAME

8       mail::folder::addMessage - Add a message to a folder
9

SYNOPSIS

11       #include <libmail/mail.H>
12
13
14       class myCallback : public mail::callback {
15       public:
16           void success(std::string msg);
17           void fail(std::string msg);
18       };
19
20       #include <libmail/addmessage.H>
21
22       mail::folder *folder;
23       time_t messageDate;
24       mail::messageInfo newMessageInfo;
25       std::string messageBody;
26
27       mail::addMessage *msg=folder->addMessage(myCallback &callback);
28
29                                                msg->messageDate=messageDate;
30                                                msg->messageInfo=messageInfo;
31                                                msg->saveMessageContents(messageBody);
32
33                                                if (changedMyMind)
34                                                    msg->fail(std::string errmsg);
35                                                else
36                                                    msg->go();
37

USAGE

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
48       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
54       The application does not need to explicitly destroy the
55       mail::addMessage object, the object is automatically destroyed by go or
56       fail.
57
58       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
62       messageDate
63           The message's timestamp, as retrieved by mail::account::ARRIVALDATE
64           parameter to mail::account::readMessageAttributes(3x)().
65
66               Note
67               This timestamp does not necessarily have to be the same as the
68               timestamp in the message's Date: header.
69
70       messageInfo
71           The message flags, as returned by
72           mail::account::getFolderIndexInfo(3x)().
73
74               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

MIME-BASED MESSAGE COMPOSITION

81           #include <libmail/mail.H>
82
83
84           class myCallback : public mail::callback {
85           public:
86               void success(std::string msg);
87               void fail(std::string msg);
88           };
89
90       mail::addMessage *msg;
91
92       msg->assembleContent(size_t &handleRet,
93                            const mail::Attachment &attachment,
94                            mail::callback &cb);
95
96       msg->assembleMessageRfc822(size_t &handleRet, std::string headers,
97                                  size_t handle, mail::callback &cb);
98
99       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
105       bool flag=msg->assemble(void);
106
107       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
120       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
126       The assembleContent method receives a mail::Attachment(3x) object.
127
128       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
135       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
143       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
152       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
161   COPYING ATTACHMENTS FROM OTHER MESSAGES
162       mail::addMessage *msg;
163
164       msg->assembleImportAttachment(size_t &handleRet, mail::account *acct,
165                                     std::string uid,
166                                     const mail::mimestruct &attachment,
167                                     mail::callback &cb);
168
169       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
176       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
185           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
189       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
197       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

RETURN CODES AND CALLBACKS

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
214           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
222           The callback object's fail method gets invoked just prior to this
223           function returning NULL, in these kinds of situations.
224
225       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
231           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
236           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

SEE ALSO

242       mail::account::getFolderIndexInfo(3x)(),
243       mail::account::readMessageAttributes(3x)().
244

AUTHOR

246       Sam Varshavchik
247
248
249
250Cone©                             08/25/2016          MAIL::FOLDER::ADDMES(3x)
Impressum