1mail::folder::setRights(m3axi)l::folder Native API refermeanicle::folder::setRights(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,
21 std::vector<std::string> &errorRights, std::string identifier,
22 std::string rights);
23
25 This function implements folder access control lists (ACLs). Access
26 control lists define who is allowed to do certain operations on a
27 folder, or on messages in the folder. Folder ACLs are implement only
28 for IMAP accounts on IMAP servers that implement access control lists.
29 This function will fail if folder is not a folder on an IMAP server
30 that supports access control lists.
31 This function changes folder's access control list entry for identi‐
33 fier. Any existing access rights for identifier are replaced by
34 rights. If the access control list does not have an entry for identi‐
35 fier, one is created. With some servers, setting identifier's rights
36 to an empty string automatically removes identifier from the access
37 control list.
38 IDENTIFIER
40 Not all servers support every one of the following access control list
41 identifiers. See the server's documentation to check which access con‐
42 trol list identifiers are implemented by the server:
43 ``anonymous'', or ``anyone''
45 This identifier refers to universal access rights given to
46 everyone, including anonymous users (if supported by server).
47 ``authuser''
49 Same as ``anyone'', except for anonymous users. If the server
50 does not implement anonymous access, then ``anonymous'', ``any‐
51 one'', and ``authuser'' are equivalent.
52 ``owner''
54 The owner of the mailbox that contains the folder.
55 ``administrators''
57 Any member of a group that's defined as an administrator group,
58 in an implementation-defined way.
59 ``user=username''
61 A single system user, identified by username.
62 ``group=groupname''
64 Any system user that's part of a group identified by groupname.
65 Groups are created and managed by IMAP server-specific tools.
66 See the server's documentation for information on creating and
67 managing groups (if the groups are even implemented by the
68 server in the first place).
69 ``-identifier''
71 An access control list identifier may be prefixed by a ``-'',
72 which refers to a ``negative right''. Negative rights explic‐
73 itly revoke the associated access rights from the identifier
74 instead of granting the right.
75 Negative rights are not implemented by all servers. See the
77 server's documentation to check if the server implements nega‐
78 tive access rights.
79 Note: username and groupname must specified using the UTF-8
81 character set.
82 ACCESS RIGHTS
84 At this time, the following access rights are supported:
85 ``a'' Administrator access: view and change folder access control
87 lists.
88 ``c'' Create subfolders.
90 ``e'' Expunge deleted messages from the folder.
92 ``i'' Insert, or add messages to the folder.
94 ``l'' List, or view the folder's existence. If a folder does not have
96 the ``l'' access right, the server will not include this folder
97 when it's asked to list all folders in the folder directory.
98 However, if the ``r'' access right is present, the folder may be
99 opened if the folder's name is known.
100 ``r'' Read, or open the folder. An attempt to open the folder will
102 fail without the ``r'' access right, even if the folder's name
103 is known.
104 ``p'' ``Post messages'' to the folder. This access right is currently
106 listed in the ACL specification; however its intention is not
107 clear, and most servers do not do anything useful with this
108 access right. It is listed here for information purposes only.
109 ``s'' Allow changing the read/unread status of messages in the folder.
111 The server will not automatically clear the unread message sta‐
112 tus flag on messages after they are read, or let this status
113 flag be explicitly changed, without the ``s'' access right.
114 ``t'' Allow tagging of messages as deleted or undeleted. The server
116 will prohibit changing the messages' deleted message status flag
117 without the ``t'' access right.
118 ``w'' Allow changing the draft, replied, and marked message status
120 flags. The server will not allow changes to these flags without
121 the ``w'' access right.
122 ``x'' Allow this folder to be removed. The server will not this
124 folder to be deleted without the ``x'' access right.
125 ADDING OR REMOVING ACCESS RIGHTS
127 If rights begins with ``+'', the remaining access rights are added to
128 any existing rights that identifier already has. If rights begins with
129 ``-'', the remaining access rights are removed from identifier existing
130 access rights.
131 EXTENDED ERROR REPORTING
133 Most IMAP servers have restrictions on which combinations of access
134 rights are valid for which folders. See the IMAP server's documenta‐
135 tion to check for any access rights restrictions. The most common
136 restriction is that the ``e'', ``t'', and ``x'' access rights must
137 either be set together, as a group, or not. The server will reject or
138 ignore an attempt to set prohibited combinations of access rights for a
139 given folder.
140 Some IMAP servers implement an extended form of the access control list
142 protocol which makes it possible to obtain the server's restrictions.
143 When an attempt to set an invalid access right combination is rejected,
144 errorIdentifier will be set to indicate which identifier's access right
145 combination was rejected (usually it will be set to the same value as
146 identifier.
147 errorRights will be set to an array of strings, each strings consisting
149 of one or more access rights. The first array element, errorRights[0]
150 will contain the minimum access rights required for this folder (which
151 may be an empty string if the folder does not require any minimum
152 access rights for the identifier). Each remaining string lists an
153 optional access right allowed for this folder. If a string contains
154 more than one access right, it means that these access rights must be
155 added or removed from the access control list together, as a group.
156
158 The application must wait until callback's success or fail method is
159 invoked. The success method is invoked when this request is succes‐
160 fully processed. The fail method is invoked if this request cannot be
161 processed. The application must not destroy callback until either the
162 success or fail method is invoked.
163 Note: callback's fail method may be invoked even after other
165 callback methods were invoked. This indicates that the request
166 was partially completed before the error was encountered.
167
169 mail::account::delRights(3x), mail::account::getMyRights(3x),
170 mail::account::getRights(3x).
171 10 April 2006 mail::folder::setRights(3x)