        Cone©

MAIL::FOLDER::ADDMES(3x)

NAME
mail::folder::addMessage - Add a message to a folder

SYNOPSIS

#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();

USAGE

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.

messageDate
    The message's timestamp, as retrieved by mail::account::ARRIVALDATE parameter to mail::account::readMessageAttributes(3x)().

        Note
        This timestamp does not necessarily have to be the same as the timestamp in the message's Date: header.

messageInfo
    The message flags, as returned by mail::account::getFolderIndexInfo(3x)().

        Note
        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.

MIME-BASED MESSAGE COMPOSITION

    #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.

  COPYING ATTACHMENTS FROM OTHER MESSAGES

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).

    Note

    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.

RETURN CODES AND CALLBACKS

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.

    Note

    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.

    Note

    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.

    Note

    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.

SEE ALSO

mail::account::getFolderIndexInfo(3x)(), mail::account::readMessageAttributes(3x)().

AUTHOR

Sam Varshavchik