1MAIL::FOLDER::SETRIG(3x)Cone: COnsole Newsreader And EMAIL::FOLDER::SETRIG(3x)
2
6 mail::folder::setRights - Change access control lists
7
9 #include <libmail/mail.H>
10 class myCallback : public mail::callback {
13 public:
14 void success(std::string msg);
15 void fail(std::string msg);
16 };
17 folder->setRights(myCallback &callback, std::string &errorIdentifier,
19 std::vector<std::string> &errorRights,
20 std::string identifier, std::string rights);
21
23 This function implements folder access control lists (ACLs). Access
24 control lists define who is allowed to do certain operations on a
25 folder, or on messages in the folder. Folder ACLs are implement only
26 for IMAP accounts on IMAP servers that implement access control lists.
27 This function will fail if folder is not a folder on an IMAP server
28 that supports access control lists.
29 This function changes folder´s access control list entry for
31 identifier. Any existing access rights for identifier are replaced by
32 rights. If the access control list does not have an entry for
33 identifier, one is created. With some servers, setting identifier´s
34 rights to an empty string automatically removes identifier from the
35 access control list.
36 Identifier
38 Not all servers support every one of the following access control list
39 identifiers. See the server´s documentation to check which access
40 control list identifiers are implemented by the server:
41 “anonymous”, or “anyone”
43 This identifier refers to universal access rights given to
44 everyone, including anonymous users (if supported by server).
45 “authuser”
47 Same as “anyone”, except for anonymous users. If the server does
48 not implement anonymous access, then “anonymous”, “anyone”, and
49 “authuser” are equivalent.
50 “owner”
52 The owner of the mailbox that contains the folder.
53 “administrators”
55 Any member of a group that´s defined as an administrator group, in
56 an implementation-defined way.
57 “user=username”
59 A single system user, identified by username.
60 “group=groupname”
62 Any system user that´s part of a group identified by groupname.
63 Groups are created and managed by IMAP server-specific tools. See
64 the server´s documentation for information on creating and managing
65 groups (if the groups are even implemented by the server in the
66 first place).
67 “-identifier”
69 An access control list identifier may be prefixed by a “-”, which
70 refers to a “negative right”. Negative rights explicitly revoke the
71 associated access rights from the identifier instead of granting
72 the right.
73 Negative rights are not implemented by all servers. See the
75 server´s documentation to check if the server implements negative
76 access rights.
77 Note
79 username and groupname must specified using the UTF-8 character
80 set.
81 Access rights
83 At this time, the following access rights are supported:
84 “a”
86 Administrator access: view and change folder access control lists.
87 “c”
89 Create subfolders.
90 “e”
92 Expunge deleted messages from the folder.
93 “i”
95 Insert, or add messages to the folder.
96 “l”
98 List, or view the folder´s existence. If a folder does not have the
99 “l” access right, the server will not include this folder when it´s
100 asked to list all folders in the folder directory. However, if the
101 “r” access right is present, the folder may be opened if the
102 folder´s name is known.
103 “r”
105 Read, or open the folder. An attempt to open the folder will fail
106 without the “r” access right, even if the folder´s name is known.
107 “p”
109 “Post messages” to the folder. This access right is currently
111 listed in the ACL specification; however its intention is not
112 clear, and most servers do not do anything useful with this access
113 right. It is listed here for information purposes only.
114 “s”
116 Allow changing the read/unread status of messages in the folder.
117 The server will not automatically clear the unread message status
118 flag on messages after they are read, or let this status flag be
119 explicitly changed, without the “s” access right.
120 “t”
122 Allow tagging of messages as deleted or undeleted. The server will
123 prohibit changing the messages´ deleted message status flag without
124 the “t” access right.
125 “w”
127 Allow changing the draft, replied, and marked message status flags.
128 The server will not allow changes to these flags without the “w”
129 access right.
130 “x”
132 Allow this folder to be removed. The server will not this folder to
133 be deleted without the “x” access right.
134 Adding or removing access rights
136 If rights begins with “+”, the remaining access rights are added to any
137 existing rights that identifier already has. If rights begins with “-”,
138 the remaining access rights are removed from identifier existing access
139 rights.
140 Extended error reporting
142 Most IMAP servers have restrictions on which combinations of access
143 rights are valid for which folders. See the IMAP server´s documentation
144 to check for any access rights restrictions. The most common
145 restriction is that the “e”, “t”, and “x” access rights must either be
146 set together, as a group, or not. The server will reject or ignore an
147 attempt to set prohibited combinations of access rights for a given
148 folder.
149 Some IMAP servers implement an extended form of the access control list
151 protocol which makes it possible to obtain the server´s restrictions.
152 When an attempt to set an invalid access right combination is rejected,
153 errorIdentifier will be set to indicate which identifier´s access right
154 combination was rejected (usually it will be set to the same value as
155 identifier.
156 errorRights will be set to an array of strings, each strings consisting
158 of one or more access rights. The first array element, errorRights[0]
159 will contain the minimum access rights required for this folder (which
160 may be an empty string if the folder does not require any minimum
161 access rights for the identifier). Each remaining string lists an
162 optional access right allowed for this folder. If a string contains
163 more than one access right, it means that these access rights must be
164 added or removed from the access control list together, as a group.
165
167 The application must wait until callback´s success or fail method is
168 invoked. The success method is invoked when this request is succesfully
169 processed. The fail method is invoked if this request cannot be
170 processed. The application must not destroy callback until either the
171 success or fail method is invoked.
172 Note
174 callback´s fail method may be invoked even after other callback
175 methods were invoked. This indicates that the request was partially
176 completed before the error was encountered.
177
179 mail::account::delRights(3x), mail::account::getMyRights(3x),
180 mail::account::getRights(3x).
181[FIXME: source] 05/08/2010 MAIL::FOLDER::SETRIG(3x)