1        Cone©
2
3MAIL::ACCOUNT::SETRI(3x)Cone: COnsole Newsreader And EMAIL::ACCOUNT::SETRI(3x)
4
5
6

NAME

8       mail::ACCOUNT::setRights - Change access control lists
9

SYNOPSIS

11       #include <libmail/sync.H>
12
13       mail::ACCOUNT *mail;
14       mail::folder *folder;
15
16       bool ok=mail->setRights(mail::folder *folder,
17                               std::string &errorIdentifier,
18                               std::vector<std::string> &errorRights,
19                               std::string identifier, std::string rights);
20

USAGE

22       This function implements folder access control lists (ACLs). Access
23       control lists define who is allowed to do certain operations on a
24       folder, or on messages in the folder. Folder ACLs are implement only
25       for IMAP accounts on IMAP servers that implement access control lists.
26       This function will fail if folder is not a folder on an IMAP server
27       that supports access control lists.
28
29       This function changes folder's access control list entry for
30       identifier. Any existing access rights for identifier are replaced by
31       rights. If the access control list does not have an entry for
32       identifier, one is created. With some servers, setting identifier's
33       rights to an empty string automatically removes identifier from the
34       access control list.
35
36   Identifier
37       Not all servers support every one of the following access control list
38       identifiers. See the server's documentation to check which access
39       control list identifiers are implemented by the server:
40
41       “anonymous”, or “anyone”
42           This identifier refers to universal access rights given to
43           everyone, including anonymous users (if supported by server).
44
45       “authuser”
46           Same as “anyone”, except for anonymous users. If the server does
47           not implement anonymous access, then “anonymous”, “anyone”, and
48           “authuser” are equivalent.
49
50       “owner”
51           The owner of the mailbox that contains the folder.
52
53       “administrators”
54           Any member of a group that's defined as an administrator group, in
55           an implementation-defined way.
56
57       “user=username
58           A single system user, identified by username.
59
60       “group=groupname
61           Any system user that's part of a group identified by groupname.
62           Groups are created and managed by IMAP server-specific tools. See
63           the server's documentation for information on creating and managing
64           groups (if the groups are even implemented by the server in the
65           first place).
66
67       “-identifier
68           An access control list identifier may be prefixed by a “-”, which
69           refers to a “negative right”. Negative rights explicitly revoke the
70           associated access rights from the identifier instead of granting
71           the right.
72
73           Negative rights are not implemented by all servers. See the
74           server's documentation to check if the server implements negative
75           access rights.
76
77           Note
78           username and groupname must specified using the UTF-8 character
79           set.
80
81   Access rights
82       At this time, the following access rights are supported:
83
84       “a”
85           Administrator access: view and change folder access control lists.
86
87       “c”
88           Create subfolders.
89
90       “e”
91           Expunge deleted messages from the folder.
92
93       “i”
94           Insert, or add messages to the folder.
95
96       “l”
97           List, or view the folder's existence. If a folder does not have the
98           “l” access right, the server will not include this folder when it's
99           asked to list all folders in the folder directory. However, if the
100           “r” access right is present, the folder may be opened if the
101           folder's name is known.
102
103       “r”
104           Read, or open the folder. An attempt to open the folder will fail
105           without the “r” access right, even if the folder's name is known.
106
107       “p”
108           “Post messages” to the folder. This access right is currently
109           listed in the ACL specification; however its intention is not
110           clear, and most servers do not do anything useful with this access
111           right. It is listed here for information purposes only.
112
113       “s”
114           Allow changing the read/unread status of messages in the folder.
115           The server will not automatically clear the unread message status
116           flag on messages after they are read, or let this status flag be
117           explicitly changed, without the “s” access right.
118
119       “t”
120           Allow tagging of messages as deleted or undeleted. The server will
121           prohibit changing the messages' deleted message status flag without
122           the “t” access right.
123
124       “w”
125           Allow changing the draft, replied, and marked message status flags.
126           The server will not allow changes to these flags without the “w”
127           access right.
128
129       “x”
130           Allow this folder to be removed. The server will not this folder to
131           be deleted without the “x” access right.
132
133   Adding or removing access rights
134       If rights begins with “+”, the remaining access rights are added to any
135       existing rights that identifier already has. If rights begins with “-”,
136       the remaining access rights are removed from identifier existing access
137       rights.
138
139   Extended error reporting
140       Most IMAP servers have restrictions on which combinations of access
141       rights are valid for which folders. See the IMAP server's documentation
142       to check for any access rights restrictions. The most common
143       restriction is that the “e”, “t”, and “x” access rights must either be
144       set together, as a group, or not. The server will reject or ignore an
145       attempt to set prohibited combinations of access rights for a given
146       folder.
147
148       Some IMAP servers implement an extended form of the access control list
149       protocol which makes it possible to obtain the server's restrictions.
150       When an attempt to set an invalid access right combination is rejected,
151       errorIdentifier will be set to indicate which identifier's access right
152       combination was rejected (usually it will be set to the same value as
153       identifier.
154
155       errorRights will be set to an array of strings, each strings consisting
156       of one or more access rights. The first array element, errorRights[0]
157       will contain the minimum access rights required for this folder (which
158       may be an empty string if the folder does not require any minimum
159       access rights for the identifier). Each remaining string lists an
160       optional access right allowed for this folder. If a string contains
161       more than one access right, it means that these access rights must be
162       added or removed from the access control list together, as a group.
163

RETURN CODES AND CALLBACKS

165       This method returns true if it succeeds, or false if it fails. If the
166       method fails, use mail::ACCOUNT::getErrmsg() to read a brief
167       description of the error.
168

SEE ALSO

170       mail::ACCOUNT::delRights(3x), mail::ACCOUNT::getMyRights(3x),
171       mail::ACCOUNT::getRights(3x).
172

AUTHOR

174       Sam Varshavchik
175
176
177
178Cone©                             08/25/2016          MAIL::ACCOUNT::SETRI(3x)
Impressum