mail::folder::getRights
Prev | mail::folder Native API reference | Next

## Name

mail::folder::getRights — Read access control list

## Synopsis

#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};

`folder->getRights(` | myCallback &callback,
| std::list<std::pair<std::string, 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 obtains `folder`'s entire access control list. If this function succeeds (this function may fail if the requesting client does not have the required access to the folder), `rights` will be initialized to an array of `identifier`/`accessrights` tuples.

### 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:

“`anonymous`”, or “`anyone`”

  This identifier refers to universal access rights given to everyone, including anonymous users (if supported by server).

“`authuser`”

  Same as “anyone”, except for anonymous users. If the server does not implement anonymous access, then “anonymous”, “anyone”, and “authuser” are equivalent.

“`owner`”

  The owner of the mailbox that contains the folder.

“`administrators`”

  Any member of a group that's defined as an administrator group, in an implementation-defined way.

“`user=``username`”

  A single system user, identified by `username`.

“`group=``groupname`”

  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).

“-`identifier`”

  An access control list identifier may be prefixed by a “-”, which refers to a “negative right”. 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:

“`a`”

  Administrator access: view and change folder access control lists.

“`c`”

  Create subfolders.

“`e`”

  Expunge deleted messages from the folder.

“`i`”

  Insert, or add messages to the folder.

“`l`”

  List, or view the folder's existence. If a folder does not have the “`l`” access right, the server will not include this folder when it's asked to list all folders in the folder directory. However, if the “`r`” access right is present, the folder may be opened if the folder's name is known.

“`r`”

  Read, or open the folder. An attempt to open the folder will fail without the “`r`” access right, even if the folder's name is known.

“`p`”

  “Post messages” 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.

“`s`”

  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 “`s`” access right.

“`t`”

  Allow tagging of messages as deleted or undeleted. The server will prohibit changing the messages' `deleted` message status flag without the “`t`” access right.

“`w`”

  Allow changing the `draft`, `replied`, and `marked` message status flags. The server will not allow changes to these flags without the “`w`” access right.

“`x`”

  Allow this folder to be removed. The server will not this folder to be deleted without the “`x`” access right.

## 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::setRights(3x).

Prev | Up | Next
mail::folder::getPath | Home | ToC | mail::folder::hasMessages