Name

mail::account::removeMessages — Remove messages from the folder

Synopsis




#include <libmail/mail.H>


class myCallback : public mail::callback {
public:
    void success(std::string msg);
    void fail(std::string msg);
};


mail::account *account;

account->removeMessages( const std::vector<size_t> msgList,
  myCallback &callback);
 

USAGE

This function removes messages from the currently open folder. msgList is a list of messages to be removed.

This request invokes methods in the currently opened folder's mail::callback::folder object, as follows:

  • mail::account::messagesRemoved is invoked for all messages removed from the folder. Obviously, this method will be invoked, one at a time, for each message identified in msgList.

    Note

    Messages are removed one at a time. Each call to mail::account::messagesRemoved renumbers the remaining messages in the folder, and depending on the account type, mail::account::messagesRemoved may not necessarily receive an exact copy of msgList. For example, with an IMAP account if msgList contains 1, 2, and 3, the mail::account::messagesRemoved function will probably be called three times. Each time it will receive a single range of removed messages, set to messages 1-1, all three times. This is because IMAP servers remove messages one message at a time. The first invocation of mail::account::messagesRemoved indicates that message #1 was removed, with the remaining messages renumbered; and old messages #2 and #3 becoming messages #1 and #2. The second invocation of mail::account::messagesRemoved's messageNumber parameter of 1 refers to the old message #2, which is now message #1. Ditto for the third invocation of mail::account::messagesRemoved.

    On the other hand, with an IMAP account the mail::account::messagesRemoved method will be invoked once, giving a single range of removed messages, 1-3. Application must be prepared to handle either situation.

  • The mail::account::messagesChanged method may be invoked for any other messages in the folder with changed status flags.

  • mail::account::newMessages may also be invoked if any messages were added to this folder. The application should use mail::account::getFolderIndexSize(3x), and compare it to the previously-known folder size, in order to determine how many messages were added to the folder (new messages are always added to the end of the message list).

Note

This request should not be used with accounts on IMAP servers that do not implement the UIDPLUS IMAP extension. UIDPLUS is required to directly support this functionality. An alternative, much slower, fallback implementation will be used with IMAP servers that do not implement this protocol extension.

Return Codes

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.