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

NAME

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

SYNOPSIS

11       #include <libmail/mail.H>
12
13
14       class myCallback : public mail::callback {
15       public:
16           void success(std::string msg);
17           void fail(std::string msg);
18       };
19
20       folder->setRights(myCallback &callback, std::string &errorIdentifier,
21                         std::vector<std::string> &errorRights,
22                         std::string identifier, std::string rights);
23

USAGE

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

RETURN CODES AND CALLBACKS

168       The application must wait until callback's success or fail method is
169       invoked. The success method is invoked when this request is succesfully
170       processed. The fail method is invoked if this request cannot be
171       processed. The application must not destroy callback until either the
172       success or fail method is invoked.
173
174           Note
175           callback's fail method may be invoked even after other callback
176           methods were invoked. This indicates that the request was partially
177           completed before the error was encountered.
178

SEE ALSO

180       mail::account::delRights(3x), mail::account::getMyRights(3x),
181       mail::account::getRights(3x).
182

AUTHOR

184       Sam Varshavchik
185
186
187
188Cone©                             08/25/2016          MAIL::FOLDER::SETRIG(3x)
Impressum