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

## Name

mail::account::updateKeywords — Update message keywords

## 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->fsfuncupdateKeywords(` | const std::vector<size_t> msgList,
| const std::set<std::string> &keywords,
| bool setOrChange,
| bool changeTo,
| myCallback &callback`)`;

`account->fsfuncupdateKeywords(` | const std::vector<size_t> msgList,
| const std::list<std::string> &keywords,
| bool setOrChange,
| bool changeTo,
| myCallback &callback`)`;

`account->fsfuncupdateKeywords(` | const std::vector<size_t> msgList,
| const std::vector<std::string> &keywords,
| bool setOrChange,
| bool changeTo,
| myCallback &callback`)`;

## USAGE

This function updates the set of keywords of one or more messages. `keywords` may also be specified as a list, or a vector (and duplicate occurences of a keyword are automatically removed). `msgList` specifies a list of messages. Messages are numbered starting with message #0 and up to one less than mail::account::getFolderIndexSize(3x)() (when `mail::account::getFolderIndexSize` returns 6, the messages are numbered 0 through 5). Only the messages that appear in `msgList` are processed by this request.

When `setOrChange` is `false`, `changeTo` is ignored, and any existing keywords set for each message in `msgList` are completely replaced by `keywords`. When `setOrChange` is `true` `changeTo` selects whether `keywords` are added to the existing set of keywords that are already set for each message (`changeTo` is `true`), or removed from the existing set of keywords (`changeTo` is `false`).

### Keywords

Keywords are application-defined flags, or markers, that are associated which each message in a folder. Keywords names are arbitrary, and are subject to certain restrictions. LibMAIL does not place any special meaning on any particular keyword name. LibMAIL 's sole involvement is to store the save the list of keywords set for a given message, and then retrieve it upon demand.

Which characters may be included in a keyword name depends on the underlying account type. Applications that expect to use any supported account type should limit themselves to the lowest common denominator: case insensitive `us-ascii` character set; no whitespace or any of the following characters: commas; apostrophes; quotes; backslashes; forward slashes; opening/closing braces, brackets, and parenthesis; question marks; asterisks; percent signs. In all cases, keyword names may not include any control characters. Unless keywords are permanently saved, and remain available after the folder is closed, and subsequently reopened. When the folder is reopened at some point later, all keywords will remain set for their corresponding messages (unless they were modified by another process).

- Temporary folders do not implement keywords.

- IMAP accounts have case-insensitive keywords in the `us-ascii` character set. Keyword names may not contain: apostrophes; quotes; backslashes; forward slashes; opening/closing braces, brackets, and parenthesis; question marks; asterisks; and percent signs.

- SMAP accounts have case-sensitive keywords that use the `UTF-8` character set. Keyword names may not contain commas.

  ### Note

  IMAP restrictions also apply if the same account is accessible via IMAP.

- Maildir accounts have case-sensitive keywords that use the `UTF-8` character set.

  ### Note

  IMAP and/or SMAP restrictions also apply if the maildir is also accessible via IMAP or SMAP.

- Mbox accounts have case-sensitive keywords that use the `UTF-8` character set.

- NNTP and POP3 accounts have case-sensitive keywords that use the `UTF-8` character set. Keywords are not saved. When the folder is closed, all set keywords are lost. Snapshots may be used to obtain permanent keyword storage for NNTP and POP3 accounts. See mail::folder::open(3x) for more information.

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

### Note

The application is notified about when a message's status changes by by invoking the `messageChanged` callback method of the currently opened folder's mail::folderCallback object. Depending on the mail server, the `messageChanged` method may be invoked as part of processing this request, or some time later after this request is completed, and `callback`'s `success` method was invoked.

## SEE ALSO

mail::account::saveFolderIndexInfo(3x), mail::account::getFolderIndexInfo(3x), mail::account::getFolderKeywordInfo(3x), mail::folder::open(3x).

Prev | Up | Next
mail::account::updateFolderIndexInfo | Home | ToC | mail::account::updateNotify