mail::folder::addMessage
Prev | mail::folder Native API reference | Next

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

Prev | Up | Next
mail::folder Native API reference | Home | ToC | mail::folder::clone