<<< Previous |  | Next >>>

# mail::folder::addMessage

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

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

<<< Previous | Home | Next >>>
`mail::folder` Native API reference | Up | mail::folder::clone