Rechercher une page de manuel
mail::folder::setRights.3x
Langue: en
Version: 11/28/2008 (fedora - 01/12/10)
Section: 3 (Bibliothèques de fonctions)
Sommaire
NAME
mail::folder::setRights - Change access control listsSYNOPSIS
-
#include <libmail/mail.H> class myCallback : public mail::callback { public: void success(std::string msg); void fail(std::string msg); };
- folder->setRights(myCallback &callback, std::string &errorIdentifier, std::vector<std::string> &errorRights, std::string identifier, std::string rights);
USAGE
- This function implements folder access control lists (ACLs). Access control lists define who is allowed to do certain operations on a folder, or on messages in the folder. Folder ACLs are implement only for IMAP accounts on IMAP servers that implement access control lists. This function will fail if folder is not a folder on an IMAP server that supports access control lists.
This function changes folder's access control list entry for identifier. Any existing access rights for identifier are replaced by rights. If the access control list does not have an entry for identifier, one is created. With some servers, setting identifier's rights to an empty string automatically removes identifier from the access control list.
Identifier
Not all servers support every one of the following access control list identifiers. See the server's documentation to check which access control list identifiers are implemented by the server:
lqanonymousrq, or lqanyonerq
- This identifier refers to universal access rights given to everyone, including anonymous users (if supported by server).
lqauthuserrq
- Same as lqanyonerq, except for anonymous users. If the server does not implement anonymous access, then lqanonymousrq, lqanyonerq, and lqauthuserrq are equivalent.
lqownerrq
- The owner of the mailbox that contains the folder.
lqadministratorsrq
- Any member of a group that's defined as an administrator group, in an implementation-defined way.
lquser=usernamerq
- A single system user, identified by username.
lqgroup=groupnamerq
- Any system user that's part of a group identified by groupname. Groups are created and managed by IMAP server-specific tools. See the server's documentation for information on creating and managing groups (if the groups are even implemented by the server in the first place).
lq-identifierrq
- An access control list identifier may be prefixed by a lq-rq, which refers to a lqnegative rightrq. Negative rights explicitly revoke the associated access rights from the identifier instead of granting the right.
Negative rights are not implemented by all servers. See the server's documentation to check if the server implements negative access rights.
Note
username and groupname must specified using the UTF-8 character set.
Access rights
At this time, the following access rights are supported:
lqarq
- Administrator access: view and change folder access control lists.
lqcrq
- Create subfolders.
lqerq
- Expunge deleted messages from the folder.
lqirq
- Insert, or add messages to the folder.
lqlrq
- List, or view the folder's existence. If a folder does not have the lqlrq access right, the server will not include this folder when it's asked to list all folders in the folder directory. However, if the lqrrq access right is present, the folder may be opened if the folder's name is known.
lqrrq
- Read, or open the folder. An attempt to open the folder will fail without the lqrrq access right, even if the folder's name is known.
lqprq
lqPost messagesrq to the folder. This access right is currently listed in the ACL specification; however its intention is not clear, and most servers do not do anything useful with this access right. It is listed here for information purposes only.
lqsrq
- Allow changing the read/unread status of messages in the folder. The server will not automatically clear the unread message status flag on messages after they are read, or let this status flag be explicitly changed, without the lqsrq access right.
lqtrq
- Allow tagging of messages as deleted or undeleted. The server will prohibit changing the messages' deleted message status flag without the lqtrq access right.
lqwrq
- Allow changing the draft, replied, and marked message status flags. The server will not allow changes to these flags without the lqwrq access right.
lqxrq
- Allow this folder to be removed. The server will not this folder to be deleted without the lqxrq access right.
Adding or removing access rights
If rights begins with lq+rq, the remaining access rights are added to any existing rights that identifier already has. If rights begins with lq-rq, the remaining access rights are removed from identifier existing access rights.
Extended error reporting
Most IMAP servers have restrictions on which combinations of access rights are valid for which folders. See the IMAP server's documentation to check for any access rights restrictions. The most common restriction is that the lqerq, lqtrq, and lqxrq access rights must either be set together, as a group, or not. The server will reject or ignore an attempt to set prohibited combinations of access rights for a given folder.
Some IMAP servers implement an extended form of the access control list protocol which makes it possible to obtain the server's restrictions. When an attempt to set an invalid access right combination is rejected, errorIdentifier will be set to indicate which identifier's access right combination was rejected (usually it will be set to the same value as identifier.
errorRights will be set to an array of strings, each strings consisting of one or more access rights. The first array element, errorRights[0] will contain the minimum access rights required for this folder (which may be an empty string if the folder does not require any minimum access rights for the identifier). Each remaining string lists an optional access right allowed for this folder. If a string contains more than one access right, it means that these access rights must be added or removed from the access control list together, as a group.
RETURN CODES AND CALLBACKS
The application must wait until callback's success or fail method is invoked. The success method is invoked when this request is succesfully processed. The fail method is invoked if this request cannot be processed. The application must not destroy callback until either the success or fail method is invoked.
Note
callback's fail method may be invoked even after other callback methods were invoked. This indicates that the request was partially completed before the error was encountered.
SEE ALSO
mail::account::delRights(3x), mail::account::getMyRights(3x), mail::account::getRights(3x).
Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre