<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::ACCOUNT::delRights</title>
<link rel="stylesheet" href="manpage.css" type="text/css"/>
<link rel="start" href="index.html" title="Cone: COnsole Newsreader And Emailer"/>
<link rel="up" href="synchronous.html" title="mail::ACCOUNT Synchronous API reference"/>
<link rel="prev" href="account-deletefolder.html" title="mail::ACCOUNT::deleteFolder"/>
<link rel="next" href="account-getfolderindexinfo.html" title="mail::ACCOUNT::getFolderIndexInfo"/>
<link xmlns="" rel="icon" href="icon.gif" type="image/gif"/>
<meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/>
<!--
Copyright 2002 - 2007 Double Precision, Inc. See COPYING for distribution
information.
-->
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center" rowspan="1">
mail::ACCOUNT::delRights</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="account-deletefolder.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
<span class="structname">mail::ACCOUNT</span> Synchronous
API reference</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="account-getfolderindexinfo.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="account-delrights" shape="rect" name="account-delrights"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::ACCOUNT::delRights — Delete an access control
list identifier</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="literallayout">
<p><br clear="none"/>
<br clear="none"/>
<br clear="none"/>
<br clear="none"/>
#include <libmail/sync.H><br clear="none"/>
<br clear="none"/>
mail::ACCOUNT *mail;<br clear="none"/>
mail::folder *folder;<br clear="none"/></p>
</div>
<div class="funcsynopsis">
<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
<tr>
<td rowspan="1" colspan="1"><code class="funcdef">bool
ok=mail-><b class="fsfunc">delRights</b>(</code></td>
<td rowspan="1" colspan="1">mail::folder * </td>
<td rowspan="1" colspan="1"><var class="pdparam">folder</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">std::string
& </td>
<td rowspan="1" colspan="1"><var class="pdparam">errorIdentifier</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">
std::vector<std::string> & </td>
<td rowspan="1" colspan="1"><var class="pdparam">errorRights</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">std::string  </td>
<td rowspan="1" colspan="1"><var class="pdparam">identifier</var><code>)</code>;</td>
</tr>
</table>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id556437" shape="rect" name="id556437"> </a>
<h2>USAGE</h2>
<p>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 <em class="replaceable"><code>folder</code></em>
is not a folder on an IMAP server that supports access
control lists.</p>
<p><code class="function">mail::folder::delRights</code>
removes <em class="replaceable"><code>identifier</code></em>
from the folder's access control list.</p>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id556484" shape="rect" name="id556484"> </a>
<h3>Identifier</h3>
<p>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:</p>
<div class="variablelist">
<dl>
<dt><span class="term">“<span class="quote"><code class="literal">anonymous</code></span>”, or
“<span class="quote"><code class="literal">anyone</code></span>”</span></dt>
<dd>
<p>This identifier refers to universal access rights
given to everyone, including anonymous users (if
supported by server).</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">authuser</code></span>”</span></dt>
<dd>
<p>Same as “<span class="quote">anyone</span>”, except for anonymous
users. If the server does not implement anonymous
access, then “<span class="quote">anonymous</span>”, “<span class="quote">anyone</span>”, and “<span class="quote">authuser</span>” are equivalent.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">owner</code></span>”</span></dt>
<dd>
<p>The owner of the mailbox that contains the
folder.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">administrators</code></span>”</span></dt>
<dd>
<p>Any member of a group that's defined as an
administrator group, in an implementation-defined
way.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">user=</code><em class="replaceable"><code>username</code></em></span>”</span></dt>
<dd>
<p>A single system user, identified by <em class="replaceable"><code>username</code></em>.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">group=</code><em class="replaceable"><code>groupname</code></em></span>”</span></dt>
<dd>
<p>Any system user that's part of a group identified
by <em class="replaceable"><code>groupname</code></em>. 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).</p>
</dd>
<dt><span class="term">“<span class="quote">-<em class="replaceable"><code>identifier</code></em></span>”</span></dt>
<dd>
<p>An access control list identifier may be prefixed
by a “<span class="quote">-</span>”,
which refers to a “<span class="quote">negative
right</span>”. Negative rights explicitly
revoke the associated access rights from the
<em class="replaceable"><code>identifier</code></em>
instead of granting the right.</p>
<p>Negative rights are not implemented by all
servers. See the server's documentation to check if
the server implements negative access rights.</p>
</dd>
</dl>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><em class="replaceable"><code>username</code></em> and
<em class="replaceable"><code>groupname</code></em> must
specified using the <code class="literal">UTF-8</code>
character set.</p>
</div>
</div>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id556719" shape="rect" name="id556719"> </a>
<h3>Access rights</h3>
<p>At this time, the following access rights are
supported:</p>
<div class="variablelist">
<dl>
<dt><span class="term">“<span class="quote"><code class="literal">a</code></span>”</span></dt>
<dd>
<p>Administrator access: view and change folder
access control lists.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">c</code></span>”</span></dt>
<dd>
<p>Create subfolders.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">e</code></span>”</span></dt>
<dd>
<p>Expunge deleted messages from the folder.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">i</code></span>”</span></dt>
<dd>
<p>Insert, or add messages to the folder.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">l</code></span>”</span></dt>
<dd>
<p>List, or view the folder's existence. If a folder
does not have the “<span class="quote"><code class="literal">l</code></span>”
access right, the server will not include this folder
when it's asked to list all folders in the folder
directory. However, if the “<span class="quote"><code class="literal">r</code></span>”
access right is present, the folder may be opened if
the folder's name is known.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">r</code></span>”</span></dt>
<dd>
<p>Read, or open the folder. An attempt to open the
folder will fail without the “<span class="quote"><code class="literal">r</code></span>”
access right, even if the folder's name is known.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">p</code></span>”</span></dt>
<dd>
<p>“<span class="quote">Post
messages</span>” 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.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">s</code></span>”</span></dt>
<dd>
<p>Allow changing the read/unread status of messages
in the folder. The server will not automatically
clear the <em class="structfield"><code>unread</code></em> message status
flag on messages after they are read, or let this
status flag be explicitly changed, without the
“<span class="quote"><code class="literal">s</code></span>” access right.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">t</code></span>”</span></dt>
<dd>
<p>Allow tagging of messages as deleted or undeleted.
The server will prohibit changing the messages'
<em class="structfield"><code>deleted</code></em>
message status flag without the “<span class="quote"><code class="literal">t</code></span>”
access right.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">w</code></span>”</span></dt>
<dd>
<p>Allow changing the <em class="structfield"><code>draft</code></em>, <em class="structfield"><code>replied</code></em>, and
<em class="structfield"><code>marked</code></em>
message status flags. The server will not allow
changes to these flags without the
“<span class="quote"><code class="literal">w</code></span>” access right.</p>
</dd>
<dt><span class="term">“<span class="quote"><code class="literal">x</code></span>”</span></dt>
<dd>
<p>Allow this folder to be removed. The server will
not this folder to be deleted without the
“<span class="quote"><code class="literal">x</code></span>” access right.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id557377" shape="rect" name="id557377"> </a>
<h3>Extended error reporting</h3>
<p>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 “<span class="quote">e</span>”,
“<span class="quote">t</span>”, and
“<span class="quote">x</span>” 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.</p>
<p>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, <em class="replaceable"><code>errorIdentifier</code></em> will be set
to indicate which identifier's access right combination was
rejected (usually it will be set to the same value as
<em class="replaceable"><code>identifier</code></em>.</p>
<p><em class="replaceable"><code>errorRights</code></em>
will be set to an array of strings, each strings consisting
of one or more access rights. The first array element,
<em class="replaceable"><code>errorRights</code></em>[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.</p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id557696" shape="rect" name="id557696"> </a>
<h2>RETURN CODES AND CALLBACKS</h2>
<p>This method returns <code class="literal">true</code> if
it succeeds, or <code class="literal">false</code> if it
fails. If the method fails, use <em class="structfield"><code>mail::ACCOUNT::getErrmsg()</code></em> to
read a brief description of the error.</p>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id557436" shape="rect" name="id557436"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="account-getmyrights.html" title="mail::ACCOUNT::getMyRights" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::getMyRights</span>(3x)</span></a>,
<a class="link" href="account-getrights.html" title="mail::ACCOUNT::getRights" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::getRights</span>(3x)</span></a>,
<a class="link" href="account-setrights.html" title="mail::ACCOUNT::setRights" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::setRights</span>(3x)</span></a>.</p>
</div>
</div>
<div class="navfooter">
<hr/>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="account-deletefolder.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="synchronous.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="account-getfolderindexinfo.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::ACCOUNT::deleteFolder </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="h" href="index.html" shape="rect">Home</a> | <a accesskey="t" href="bk01-toc.html" shape="rect">ToC</a></td>
<td width="40%" align="right" valign="top" rowspan="1" colspan="1"> mail::ACCOUNT::getFolderIndexInfo</td>
</tr>
</table>
</div>
</body>
</html>
