mail::ACCOUNT::updateKeywords — Update message keywords
#include <libmail/sync.H>
mail::ACCOUNT *mail;
bool
ok=mail->updateKeywords( |
const std::vector<size_t> msgList, |
| const std::set<std::string> &keywords, | |
| bool setOrChange, | |
bool changeTo); |
bool
ok=mail->updateKeywords( |
const std::vector<size_t> msgList, |
| const std::list<std::string> &keywords, | |
| bool setOrChange, | |
bool changeTo); |
bool
ok=mail->updateKeywords( |
const std::vector<size_t> msgList, |
| const std::vector<std::string> &keywords, | |
| bool setOrChange, | |
bool changeTo); |
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 a message is removed from the folder, by
mail::ACCOUNT::updateFolderIndexInfo(3x),
the following messages are renumbered accordingly.
Most mail servers allow multiple applications to open the same folder. Therefore, changes to the folder's contents can occur at any time. Before making this request, the application should use mail::ACCOUNT::checkNewMail(3x) to verify that no unexpected changes have been made to the folder's contents.
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 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.
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.
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.