mail::folder::addMessage — Add a message to a folder
#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};
#include <libmail/addmessage.H>
mail::folder *folder;
time_t messageDate;
mail::messageInfo newMessageInfo;
std::string messageBody;
mail::addMessage
*msg=folder->addMessage( |
myCallback &callback); |
msg->messageDate=messageDate;
msg->messageInfo=messageInfo;
msg->saveMessageContents(messageBody);
if (changedMyMind)
msg->fail(std::string errmsg);
else
msg->go();
This method begins the process of manually adding a
message to a folder. The mail::folder::addMessage method returns a
pointer to a mail::addMessage
object. The application should then define the contents of
the message by invoking the object's saveMessageContents method. The entire
contents of the message does not have to be specified at
once. A large message may be defined by repeatedly invoking
saveMessageContents,
consecutively, each time specifying the next portion of the
message's contents.
After the contents of the message are defined by invoking
saveMessageContents, the
application must invoke the go
method in order to actually place the new message into the
folder. The application may abort the process at any time by
invoking the fail method, and
specifying the error message.
The application does not need to explicitly destroy the
mail::addMessage object, the
object is automatically destroyed by go or fail.
The application may set the following mail::addMessage fields prior to invoking
go. If not initialized, the
following fields will be set to their default values.
The message's timestamp, as retrieved by
mail::account::ARRIVALDATE
parameter to mail::account::readMessageAttributes(3x)().
This timestamp does not necessarily have to be the
same as the timestamp in the message's Date: header.
The message flags, as returned by mail::account::getFolderIndexInfo(3x)().
The contents of uid, the message's
unique ID, are ignored, only the message flags in
messageInfo
are read. The message gets automatically assigned a
new unique ID when it gets added to the folder.
#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};
mail::addMessage *msg;
msg->assembleContent( |
size_t &handleRet, |
| const mail::Attachment &attachment, | |
mail::callback
&cb); |
msg->assembleMessageRfc822( |
size_t &handleRet, |
| std::string headers, | |
| size_t handle, | |
mail::callback
&cb); |
msg->assembleMultipart( |
size_t &handleRet, |
| std::string headers, | |
| const std::vector<size_t> parts, | |
| std::string multipart_type, | |
| const mail::mimestruct::parameterList &options, | |
mail::callback
&cb); |
bool
flag=msg->assemble( |
void); |
This is an alternative way of adding a message to a folder
by assembling it one MIME section at a time. First, use the
assembleContent method to
specify the individual content-containing (non-multipart and non-message/rfc822) MIME sections. Before
assembleContent invokes
cb's success method it will initialize
handleRet with a
“handle” that refers to this MIME
section. Use these MIME section handles to assemble the
individual MIME sections into multipart and message/rfc822 MIME sections. The
assembleMessageRfc822 and
assembleMultipart methods also
create a new MIME section handle, which refers to the
assembled MIME section, in the same way. Those handles
themselves may also be re-assembled into higher-level
multipart or message/rfc822 MIME sections.
Finally, after defining the topmost MIME section, use
assemble to assemble the entire
message. If assemble returns
true, use the go (or the fail) method. If assemble returns false, an errno-related error has occured; the
application should call fail to
report it, and clean up the mail::addMessage object.
The assembleContent method
receives a mail::Attachment(3x)
object.
The second parameter to assembleMessageRfc822 are the MIME headers
of the message/rfc822
attachment. The MIME headers must be terminated by a single
newline character, and include the Content-Type header. In nearly all
situations, this parameter should be set to the fixed string
“Content-Type:
message/rfc822\n” (note the trailing newline).
The third parameter is the handle of the attachment's
top-level MIME section.
The second parameter to assembleMultipart is a string containing
MIME headers for the multipart MIME section. These headers
should not include the
Content-Type header. The
Content-Type header for the
multipart section will be generated internally. If there are
any extra headers, they must have a single trailing newline
character. Most situations do not need extra headers, so this
parameter should be an empty string, “”.
The third parameter to assembleMultipart is the vector of
previously-defined handles of each MIME section that's to be
assembled into a multipart MIME section. The fourth parameter
is the actual MIME type of this section, usually “multipart/mixed”
or “multipart/alternative” (any
“multipart” type is allowed). The fifth
parameter is optional, and specifies the MIME content type
parameter list (the parameter list should not include the
“boundary” parameter, because it's taken
care of automatically by this function).
The last parameter to assembleContent, assembleMessageRfc822, or assembleMultipart is the callback object.
The callback object's success
method will be invoked when the MIME section has been
assembled. The fail method will
be invoked if an error occured. Depending on the type of the
folder the message is being added to, the MIME section may be
assembled immediately (in which case success or fail gets called right before the function
terminates) or the function will terminate immediately, and
the callback function will be called at a later time.
mail::addMessage *msg;
msg->assembleImportAttachment( |
size_t &handleRet, |
| mail::account *acct, | |
| std::string uid, | |
| const mail::mimestruct &attachment, | |
mail::callback
&cb); |
msg->assembleRemoveAttachmentsFrom( |
size_t &handleRet, |
| mail::account *acct, | |
| std::string uid, | |
| const mail::mimestruct &attachment, | |
| const std::set &mimeIdList, | |
mail::callback
&cb); |
The assembleImportAttachment function
assembles a new MIME section by copying an existing MIME
section from another message. acct specifies an open mail
account, with an open mail folder. uid specifies the unique
identifier of a message in acct's open folder, which can
be obtained from mail::account::getFolderIndexInfo(3x).
attachment
specifies which attachment in message uid should be copied.
attachment must be
obtained using mail::account::MIMESTRUCTURE with
mail::account::readMessageAttributes(3x).
acct can refer
to any open mail account or folder, and does not have to
be the same folder the message is being added to!
attachment may
refer to a multipart, or a non-multipart MIME section. An
attachment
referring to a multipart MIME section imports the entire
multipart MIME section, and all subsections it contains.
assembleRemoveAttachmentsFrom
also copies the entire multipart MIME section, but skips
selected MIME subsections. Any subsection appearing in
mimeIdList is not
copied. mimeIdList
is a list of MIME section identifiers, obtained from
mail::mimestruct(3x)'s
mime_id
field.
assembleRemoveAttachmentsFrom implements
the “Remove
Attachments” function in a typical mail
client, which removes individual attachments from a
message. To do that, set attachment to the top-level
MIME section that refers to the entire message (literally
the same object returned by mail::account::readMessageAttributes(3x))
and specify the attachments to remove in mimeIdList. Use mail::folder::addMessage(3x)
to add the message to the same folder as the original
message (this must be done before invoking assembleRemoveAttachmentsFrom, of
course), then when that's done remove the original
message.
mail::addMessage::fail
automatically invokes the callback object's fail method, prior to returning.
mail::addMessage::go
automatically invokes the callback object's success method, when the message is added.
mail::addMessage::go will
invoke fail if the message
cannot be added to the folder, for some reason.
The mail::folder::addMessage function returns
a NULL pointer if the mail::addMessage object cannot be
created. This does not necessarily indicate an
out-of-memory condition. It is not possible to manually add
messages to some types of folders. For example, messages
cannot be manually added to POP3 folders, since this is not
supported by the POP3 protocol.
The callback object's fail
method gets invoked just prior to this function returning
NULL, in these kinds of situations.
The application must wait until callback's success or fail method is invoked. The success method is invoked when this request
is succesfully processed. The fail method is invoked if this request
cannot be processed. The application must not destroy
callback until either
the success or fail method is invoked.
callback's
fail method may be invoked
even after other callback methods were invoked. This
indicates that the request was partially completed before
the error was encountered.
folder does not
necessarily have to be a mail::folder object that refers to the
currently open folder. Any mail::folder object from an active
mail::account object may be
used.