1mail::folder::addMessagem(a3ixl)::folder Native API refemraeinlc:e:folder::addMessage(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);
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 con‐
42 tents of the message by invoking the object's saveMessageContents
43 method. The entire contents of the message does not have to be speci‐
44 fied at once. A large message may be defined by repeatedly invoking
45 saveMessageContents, consecutively, each time specifying the next por‐
46 tion of the message's contents.
47 After the contents of the message are defined by invoking saveMessage‐
49 Contents, the application must invoke the go method in order to actu‐
50 ally place the new message into the folder. The application may abort
51 the process at any time by invoking the fail method, and specifying the
52 error message.
53 The application does not need to explicitly destroy the mail::addMes‐
55 sage object, the object is automatically destroyed by go or fail.
56 The application may set the following mail::addMessage fields prior to
58 invoking go. If not initialized, the following fields will be set to
59 their default values.
60 messageDate
62 The message's timestamp, as retrieved by mail::account::ARRIVAL‐
63 DATE parameter to mail::account::readMessageAttributes(3x)().
64 Note: This timestamp does not necessarily have to be the same as
66 the timestamp in the message's Date: header.
67 messageInfo
69 The message flags, as returned by mail::account::getFolderIndex‐
70 Info(3x)().
71 Note: The contents of uid, the message's unique ID, are ignored,
73 only the message flags in messageInfo are read. The message
74 gets automatically assigned a new unique ID when it gets added
75 to the folder.
76
78 #include <libmail/mail.H>
79 class myCallback : public mail::callback {
82 public:
83 void success(std::string msg);
84 void fail(std::string msg);
85 };
86 mail::addMessage *msg;
88 msg->assembleContent (size_t &handleRet, const mail::Attachment
90 &attachment, mail::callback &cb);
91 msg->assembleMessageRfc822 (size_t &handleRet, std::string headers,
93 size_t handle, mail::callback &cb);
94 msg->assembleMultipart (size_t &handleRet, std::string headers, const
96 std::vector<size_t> parts, std::string multipart_type, const
97 mail::mimestruct::parameterList &options, mail::callback &cb);
98 bool flag=msg->assemble(void);
100 This is an alternative way of adding a message to a folder by assem‐
102 bling it one MIME section at a time. First, use the assembleContent
103 method to specify the individual content-containing (non-multipart and
104 non-message/rfc822) MIME sections. Before assembleContent invokes cb's
105 success method it will initialize handleRet with a ``handle'' that
106 refers to this MIME section. Use these MIME section handles to assem‐
107 ble the individual MIME sections into multipart and message/rfc822 MIME
108 sections. The assembleMessageRfc822 and assembleMultipart methods also
109 create a new MIME section handle, which refers to the assembled MIME
110 section, in the same way. Those handles themselves may also be re-
111 assembled into higher-level multipart or message/rfc822 MIME sections.
112 Finally, after defining the topmost MIME section, use assemble to
114 assemble the entire message. If assemble returns true, use the go (or
115 the fail) method. If assemble returns false, an errno-related error
116 has occured; the application should call fail to report it, and clean
117 up the mail::addMessage object.
118 The assembleContent method receives a mail::Attachment(3x) object.
120 The second parameter to assembleMessageRfc822 are the MIME headers of
122 the message/rfc822 attachment. The MIME headers must be terminated by
123 a single newline character, and include the Content-Type header. In
124 nearly all situations, this parameter should be set to the fixed string
125 ``Content-Type: message/rfc822\n'' (note the trailing newline). The
126 third parameter is the handle of the attachment's top-level MIME sec‐
127 tion.
128 The second parameter to assembleMultipart is a string containing MIME
130 headers for the multipart MIME section. These headers should not
131 include the Content-Type header. The Content-Type header for the mul‐
132 tipart section will be generated internally. If there are any extra
133 headers, they must have a single trailing newline character. Most sit‐
134 uations do not need extra headers, so this parameter should be an empty
135 string, ``''.
136 The third parameter to assembleMultipart is the vector of previously-
138 defined handles of each MIME section that's to be assembled into a mul‐
139 tipart MIME section. The fourth parameter is the actual MIME type of
140 this section, usually ``multipart/mixed'' or ``multipart/alternative''
141 (any ``multipart'' type is allowed). The fifth parameter is optional,
142 and specifies the MIME content type parameter list (the parameter list
143 should not include the ``boundary'' parameter, because it's taken care
144 of automatically by this function).
145 The last parameter to assembleContent, assembleMessageRfc822, or assem‐
147 bleMultipart is the callback object. The callback object's success
148 method will be invoked when the MIME section has been assembled. The
149 fail method will be invoked if an error occured. Depending on the type
150 of the folder the message is being added to, the MIME section may be
151 assembled immediately (in which case success or fail gets called right
152 before the function terminates) or the function will terminate immedi‐
153 ately, and the callback function will be called at a later time.
154 COPYING ATTACHMENTS FROM OTHER MESSAGES
156 mail::addMessage *msg;
157 msg->assembleImportAttachment (size_t &handleRet, mail::account *acct,
159 std::string uid, const mail::mimestruct &attachment, mail::callback
160 &cb);
161 msg->assembleRemoveAttachmentsFrom (size_t &handleRet, mail::account
163 *acct, std::string uid, const mail::mimestruct &attachment, const
164 std::set &mimeIdList, mail::callback &cb);
165 The assembleImportAttachment function assembles a new MIME section by
167 copying an existing MIME section from another message. acct specifies
168 an open mail account, with an open mail folder. uid specifies the
169 unique identifier of a message in acct's open folder, which can be
170 obtained from mail::account::getFolderIndexInfo(3x). attachment speci‐
171 fies which attachment in message uid should be copied. attachment must
172 be obtained using mail::account::MIMESTRUCTURE with
173 mail::account::readMessageAttributes(3x).
174 Note: acct can refer to any open mail account or folder, and
176 does not have to be the same folder the message is being added
177 to!
178 attachment may refer to a multipart, or a non-multipart MIME section.
180 An attachment referring to a multipart MIME section imports the entire
181 multipart MIME section, and all subsections it contains. assembleRe‐
182 moveAttachmentsFrom also copies the entire multipart MIME section, but
183 skips selected MIME subsections. Any subsection appearing in mimeI‐
184 dList is not copied. mimeIdList is a list of MIME section identifiers,
185 obtained from mail::mimestruct(3x)'s mime_id field.
186 assembleRemoveAttachmentsFrom implements the ``Remove Attachments''
188 function in a typical mail client, which removes individual attachments
189 from a message. To do that, set attachment to the top-level MIME sec‐
190 tion that refers to the entire message (literally the same object
191 returned by mail::account::readMessageAttributes(3x)) and specify the
192 attachments to remove in mimeIdList. Use mail::folder::addMessage(3x)
193 to add the message to the same folder as the original message (this
194 must be done before invoking assembleRemoveAttachmentsFrom, of course),
195 then when that's done remove the original message.
196
198 mail::addMessage::fail automatically invokes the callback object's fail
199 method, prior to returning. mail::addMessage::go automatically invokes
200 the callback object's success method, when the message is added.
201 mail::addMessage::go will invoke fail if the message cannot be added to
202 the folder, for some reason.
203 Note:
205 The mail::folder::addMessage function returns a NULL pointer if
207 the mail::addMessage object cannot be created. This does not
208 necessarily indicate an out-of-memory condition. It is not pos‐
209 sible to manually add messages to some types of folders. For
210 example, messages cannot be manually added to POP3 folders,
211 since this is not supported by the POP3 protocol.
212 The callback object's fail method gets invoked just prior to
214 this function returning NULL, in these kinds of situations.
215 The application must wait until callback's success or fail method is
217 invoked. The success method is invoked when this request is succes‐
218 fully processed. The fail method is invoked if this request cannot be
219 processed. The application must not destroy callback until either the
220 success or fail method is invoked.
221 Note: callback's fail method may be invoked even after other
223 callback methods were invoked. This indicates that the request
224 was partially completed before the error was encountered.
225 Note: folder does not necessarily have to be a mail::folder
227 object that refers to the currently open folder. Any
228 mail::folder object from an active mail::account object may be
229 used.
230
232 mail::account::getFolderIndexInfo(3x)(), mail::account::readMessageAt‐
233 tributes(3x)().
234 10 April 2006 mail::folder::addMessage(3x)