mail::ACCOUNT::updateKeywords(3x)

1mail::ACCOUNT::updatemKaeiylw:o:rAdCsC(O3UxN)T SynchronousmAaPiIl:r:eAfCeCrOeUnNcTe::updateKeywords(3x)
2
3
4

NAME

6       mail::ACCOUNT::updateKeywords - Update message keywords
7

SYNOPSIS

9       #include <libmail/sync.H>
10
11       mail::ACCOUNT *mail;
12
13
14
15       bool  ok=mail->updateKeywords (const std::vector<size_t> msgList, const
16       std::set<std::string> &keywords, bool setOrChange, bool changeTo);
17
18
19
20       bool ok=mail->updateKeywords (const std::vector<size_t> msgList,  const
21       std::list<std::string> &keywords, bool setOrChange, bool changeTo);
22
23
24
25       bool  ok=mail->updateKeywords (const std::vector<size_t> msgList, const
26       std::vector<std::string> &keywords, bool setOrChange, bool changeTo);
27

USAGE

29       This function updates the set of keywords  of  one  or  more  messages.
30       keywords  may  also  be specified as a list, or a vector (and duplicate
31       occurences of a keyword are automatically removed).
32
33       msgList specifies a list of messages.  Messages are  numbered  starting
34       with  message #0 and up to one less than mail::ACCOUNT::getFolderIndex‐
35       Size(3x) (when mail::account::getFolderIndexSize returns  6,  the  mes‐
36       sages  are  numbered  0  through  5).  Only the messages that appear in
37       msgList are processed by this request.  When a message is removed  from
38       the  folder, by mail::ACCOUNT::updateFolderIndexInfo(3x), the following
39       messages are renumbered accordingly.
40
41              Note: Most mail servers allow multiple applications to open  the
42              same  folder.   Therefore,  changes to the folder's contents can
43              occur at any time.  Before making this request, the  application
44              should  use  mail::ACCOUNT::checkNewMail(3x)  to  verify that no
45              unexpected changes have been made to the folder's contents.
46
47       When setOrChange is false, changeTo is ignored, and any  existing  key‐
48       words  set  for each message in msgList are completely replaced by key‐
49       words.  When setOrChange is true changeTo selects whether keywords  are
50       added  to  the  existing  set of keywords that are already set for each
51       message (changeTo is true), or removed from the existing  set  of  key‐
52       words (changeTo is false).
53
54   KEYWORDS
55       Keywords are application-defined flags, or markers, that are associated
56       which each message in a folder.  Keywords names are arbitrary, and  are
57       subject  to  certain  restrictions.  LibMAIL does not place any special
58       meaning on any particular keyword name.  LibMAIL 's sole involvement is
59       to  store  the  save  the list of keywords set for a given message, and
60       then retrieve it upon demand.
61
62       Which characters may be included in  a  keyword  name  depends  on  the
63       underlying account type.  Applications that expect to use any supported
64       account type should limit themselves to the lowest common  denominator:
65       case  insensitive  us-ascii  character set; no whitespace or any of the
66       following characters: commas; apostrophes; quotes; backslashes; forward
67       slashes;  opening/closing  braces,  brackets, and parenthesis; question
68       marks; asterisks; percent signs.  In all cases, keyword names  may  not
69       include any control characters.  Unless keywords are permanently saved,
70       and remain available after  the  folder  is  closed,  and  subsequently
71       reopened.   When  the  folder is reopened at some point later, all key‐
72       words will remain set for their  corresponding  messages  (unless  they
73       were modified by another process).
74
75       · Temporary folders do not implement keywords.
76
77       · IMAP  accounts have case-insensitive keywords in the us-ascii charac‐
78         ter set.  Keyword names may not contain: apostrophes;  quotes;  back‐
79         slashes;  forward  slashes;  opening/closing  braces,  brackets,  and
80         parenthesis; question marks; asterisks; and percent signs.
81
82       · SMAP accounts have case-sensitive keywords that use the UTF-8 charac‐
83         ter set.  Keyword names may not contain commas.
84
85         Note:  IMAP restrictions also apply if the same account is accessible
86         via IMAP.
87
88       · Maildir accounts have case-sensitive  keywords  that  use  the  UTF-8
89         character set.
90
91         Note: IMAP and/or SMAP restrictions also apply if the maildir is also
92         accessible via IMAP or SMAP.
93
94       · Mbox accounts have case-sensitive keywords that use the UTF-8 charac‐
95         ter set.
96
97       · NNTP  and  POP3  accounts  have  case-sensitive keywords that use the
98         UTF-8 character set.  Keywords are not saved.   When  the  folder  is
99         closed,  all  set keywords are lost.  Snapshots may be used to obtain
100         permanent  keyword  storage  for  NNTP  and   POP3   accounts.    See
101         mail::folder::open(3x) for more information.
102

RETURN CODES

104       This  method returns true if it succeeds, or false if it fails.  If the
105       method fails, use mail::ACCOUNT::getErrmsg() to read a  brief  descrip‐
106       tion of the error.
107

NAME

SYNOPSIS

USAGE

RETURN CODES

SEE ALSO