mail::account::removeMessages
Prev | mail::account Native API reference | Next

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

## SEE ALSO

mail::account::saveFolderIndexInfo(3x), mail::account::getFolderIndexInfo(3x), mail::account::updateNotify(3x).

Prev | Up | Next
mail::account::readTopLevelFolders | Home | ToC | mail::account::resume