1mail::ACCOUNT::setRigmhatisl(:3:xA)CCOUNT Synchronous API rmeafielr:e:nAcCeCOUNT::setRights(3x)
2
6 mail::ACCOUNT::setRights - Change access control lists
7
9 #include <libmail/sync.H>
10 mail::ACCOUNT *mail;
12 mail::folder *folder;
13 bool ok=mail->setRights (mail::folder *folder, std::string &errorIden‐
17 tifier, std::vector<std::string> &errorRights, std::string identifier,
18 std::string rights);
19
21 This function implements folder access control lists (ACLs). Access
22 control lists define who is allowed to do certain operations on a
23 folder, or on messages in the folder. Folder ACLs are implement only
24 for IMAP accounts on IMAP servers that implement access control lists.
25 This function will fail if folder is not a folder on an IMAP server
26 that supports access control lists.
27 This function changes folder's access control list entry for identi‐
29 fier. Any existing access rights for identifier are replaced by
30 rights. If the access control list does not have an entry for identi‐
31 fier, one is created. With some servers, setting identifier's rights
32 to an empty string automatically removes identifier from the access
33 control list.
34 IDENTIFIER
36 Not all servers support every one of the following access control list
37 identifiers. See the server's documentation to check which access con‐
38 trol list identifiers are implemented by the server:
39 ``anonymous'', or ``anyone''
41 This identifier refers to universal access rights given to
42 everyone, including anonymous users (if supported by server).
43 ``authuser''
45 Same as ``anyone'', except for anonymous users. If the server
46 does not implement anonymous access, then ``anonymous'', ``any‐
47 one'', and ``authuser'' are equivalent.
48 ``owner''
50 The owner of the mailbox that contains the folder.
51 ``administrators''
53 Any member of a group that's defined as an administrator group,
54 in an implementation-defined way.
55 ``user=username''
57 A single system user, identified by username.
58 ``group=groupname''
60 Any system user that's part of a group identified by groupname.
61 Groups are created and managed by IMAP server-specific tools.
62 See the server's documentation for information on creating and
63 managing groups (if the groups are even implemented by the
64 server in the first place).
65 ``-identifier''
67 An access control list identifier may be prefixed by a ``-'',
68 which refers to a ``negative right''. Negative rights explic‐
69 itly revoke the associated access rights from the identifier
70 instead of granting the right.
71 Negative rights are not implemented by all servers. See the
73 server's documentation to check if the server implements nega‐
74 tive access rights.
75 Note: username and groupname must specified using the UTF-8
77 character set.
78 ACCESS RIGHTS
80 At this time, the following access rights are supported:
81 ``a'' Administrator access: view and change folder access control
83 lists.
84 ``c'' Create subfolders.
86 ``e'' Expunge deleted messages from the folder.
88 ``i'' Insert, or add messages to the folder.
90 ``l'' List, or view the folder's existence. If a folder does not have
92 the ``l'' access right, the server will not include this folder
93 when it's asked to list all folders in the folder directory.
94 However, if the ``r'' access right is present, the folder may be
95 opened if the folder's name is known.
96 ``r'' Read, or open the folder. An attempt to open the folder will
98 fail without the ``r'' access right, even if the folder's name
99 is known.
100 ``p'' ``Post messages'' to the folder. This access right is currently
102 listed in the ACL specification; however its intention is not
103 clear, and most servers do not do anything useful with this
104 access right. It is listed here for information purposes only.
105 ``s'' Allow changing the read/unread status of messages in the folder.
107 The server will not automatically clear the unread message sta‐
108 tus flag on messages after they are read, or let this status
109 flag be explicitly changed, without the ``s'' access right.
110 ``t'' Allow tagging of messages as deleted or undeleted. The server
112 will prohibit changing the messages' deleted message status flag
113 without the ``t'' access right.
114 ``w'' Allow changing the draft, replied, and marked message status
116 flags. The server will not allow changes to these flags without
117 the ``w'' access right.
118 ``x'' Allow this folder to be removed. The server will not this
120 folder to be deleted without the ``x'' access right.
121 ADDING OR REMOVING ACCESS RIGHTS
123 If rights begins with ``+'', the remaining access rights are added to
124 any existing rights that identifier already has. If rights begins with
125 ``-'', the remaining access rights are removed from identifier existing
126 access rights.
127 EXTENDED ERROR REPORTING
129 Most IMAP servers have restrictions on which combinations of access
130 rights are valid for which folders. See the IMAP server's documenta‐
131 tion to check for any access rights restrictions. The most common
132 restriction is that the ``e'', ``t'', and ``x'' access rights must
133 either be set together, as a group, or not. The server will reject or
134 ignore an attempt to set prohibited combinations of access rights for a
135 given folder.
136 Some IMAP servers implement an extended form of the access control list
138 protocol which makes it possible to obtain the server's restrictions.
139 When an attempt to set an invalid access right combination is rejected,
140 errorIdentifier will be set to indicate which identifier's access right
141 combination was rejected (usually it will be set to the same value as
142 identifier.
143 errorRights will be set to an array of strings, each strings consisting
145 of one or more access rights. The first array element, errorRights[0]
146 will contain the minimum access rights required for this folder (which
147 may be an empty string if the folder does not require any minimum
148 access rights for the identifier). Each remaining string lists an
149 optional access right allowed for this folder. If a string contains
150 more than one access right, it means that these access rights must be
151 added or removed from the access control list together, as a group.
152
154 This method returns true if it succeeds, or false if it fails. If the
155 method fails, use mail::ACCOUNT::getErrmsg() to read a brief descrip‐
156 tion of the error.
157
159 mail::ACCOUNT::delRights(3x), mail::ACCOUNT::getMyRights(3x),
160 mail::ACCOUNT::getRights(3x).
161 10 April 2006 mail::ACCOUNT::setRights(3x)