mail::account::updateKeywords(3x)

1mail::account::updateKemyawiolr:d:sa(c3cxo)unt Native APImarielf:e:raecnccoeunt::updateKeywords(3x)
2
3
4

NAME

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

SYNOPSIS

9       #include <libmail/mail.H>
10
11
12       class myCallback : public mail::callback {
13       public:
14           void success(std::string msg);
15           void fail(std::string msg);
16       };
17
18       mail::account *account;
19
20
21
22       account->updateKeywords   (const   std::vector<size_t>  msgList,  const
23       std::set<std::string>  &keywords,  bool  setOrChange,  bool   changeTo,
24       myCallback &callback);
25
26
27
28       account->updateKeywords   (const   std::vector<size_t>  msgList,  const
29       std::list<std::string>  &keywords,  bool  setOrChange,  bool  changeTo,
30       myCallback &callback);
31
32
33
34       account->updateKeywords   (const   std::vector<size_t>  msgList,  const
35       std::vector<std::string> &keywords, bool  setOrChange,  bool  changeTo,
36       myCallback &callback);
37

USAGE

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

RETURN CODES

105       The  application  must  wait until callback's success or fail method is
106       invoked.  The success method is invoked when this  request  is  succes‐
107       fully  processed.  The fail method is invoked if this request cannot be
108       processed.  The application must not destroy callback until either  the
109       success or fail method is invoked.
110
111              Note:  callback's  fail  method  may be invoked even after other
112              callback methods were invoked.  This indicates that the  request
113              was partially completed before the error was encountered.
114
115              Note:  The application is notified about when a message's status
116              changes by by invoking the messageChanged callback method of the
117              currently  opened folder's mail::folderCallback object.  Depend‐
118              ing on the mail server, the messageChanged method may be invoked
119              as  part  of  processing  this request, or some time later after
120              this request is completed, and  callback's  success  method  was
121              invoked.
122

NAME

SYNOPSIS

USAGE

RETURN CODES

SEE ALSO