/usr/share/cone/folder-setrights.html is in cone 0.89-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 | <html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::folder::setRights</title>
<link rel="stylesheet" href="manpage.css" type="text/css"/>
<link rel="home" href="index.html" title="Cone: COnsole Newsreader And Emailer"/>
<link rel="up" href="libmail-folder.html" title="mail::folder Native API reference"/>
<link rel="prev" href="folder-renamefolder.html" title="mail::folder::renameFolder"/>
<link rel="next" href="folder-tostring.html" title="mail::folder::toString"/>
<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::folder::setRights</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="folder-renamefolder.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
<span class="structname">mail::folder</span> Native API
reference</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="folder-tostring.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" title="mail::folder::setRights">
<a id="folder-setrights" shape="rect" name="folder-setrights"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::folder::setRights — Change access control
lists</p>
</div>
<div class="refsynopsisdiv" title="Synopsis">
<h2>Synopsis</h2>
<div class="literallayout">
<p><br clear="none"/>
<br clear="none"/>
<br clear="none"/>
#include <libmail/mail.H><br clear="none"/>
<br clear="none"/>
<br clear="none"/>
class myCallback : public mail::callback {<br clear="none"/>
public:<br clear="none"/>
    void success(std::string msg);<br clear="none"/>
    void fail(std::string msg);<br clear="none"/>
};<br clear="none"/></p>
</div>
<div class="funcsynopsis">
<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
<tr>
<td rowspan="1" colspan="1"><code class="funcdef">folder-><b class="fsfunc">setRights</b>(</code></td>
<td rowspan="1" colspan="1">myCallback &<var class="pdparam">callback</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">std::string
&<var class="pdparam">errorIdentifier</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">
std::vector<std::string> &<var class="pdparam">errorRights</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">std::string <var class="pdparam">identifier</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">std::string <var class="pdparam">rights</var><code>)</code>;</td>
</tr>
</table>
<div class="funcprototype-spacer">
 
</div>
</div>
</div>
<div class="refsect1" title="USAGE">
<a id="id641175" shape="rect" name="id641175"> </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>This function changes <em class="parameter"><code>folder</code></em>'s access control list
entry for <em class="replaceable"><code>identifier</code></em>. Any existing
access rights for <em class="replaceable"><code>identifier</code></em> are replaced by
<em class="replaceable"><code>rights</code></em>. If the
access control list does not have an entry for <em class="replaceable"><code>identifier</code></em>, one is created.
With some servers, setting <em class="replaceable"><code>identifier</code></em>'s rights to an
empty string automatically removes <em class="replaceable"><code>identifier</code></em> from the access
control list.</p>
<div class="refsect2" title="Identifier">
<a id="id641237" shape="rect" name="id641237"> </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">“<span class="quote"><code class="literal">anonymous</code></span>”</span>, or
<span class="quote">“<span class="quote"><code class="literal">anyone</code></span>”</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">“<span class="quote"><code class="literal">authuser</code></span>”</span></span></dt>
<dd>
<p>Same as <span class="quote">“<span class="quote">anyone</span>”</span>, except for
anonymous users. If the server does not implement
anonymous access, then <span class="quote">“<span class="quote">anonymous</span>”</span>, <span class="quote">“<span class="quote">anyone</span>”</span>, and <span class="quote">“<span class="quote">authuser</span>”</span> are
equivalent.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">owner</code></span>”</span></span></dt>
<dd>
<p>The owner of the mailbox that contains the
folder.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">administrators</code></span>”</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">“<span class="quote"><code class="literal">user=</code><em class="replaceable"><code>username</code></em></span>”</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">“<span class="quote"><code class="literal">group=</code><em class="replaceable"><code>groupname</code></em></span>”</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">“<span class="quote">-<em class="replaceable"><code>identifier</code></em></span>”</span></span></dt>
<dd>
<p>An access control list identifier may be prefixed
by a <span class="quote">“<span class="quote">-</span>”</span>, which refers to a
<span class="quote">“<span class="quote">negative right</span>”</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" title="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" title="Access rights">
<a id="id641475" shape="rect" name="id641475"> </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">“<span class="quote"><code class="literal">a</code></span>”</span></span></dt>
<dd>
<p>Administrator access: view and change folder
access control lists.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">c</code></span>”</span></span></dt>
<dd>
<p>Create subfolders.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">e</code></span>”</span></span></dt>
<dd>
<p>Expunge deleted messages from the folder.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">i</code></span>”</span></span></dt>
<dd>
<p>Insert, or add messages to the folder.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">l</code></span>”</span></span></dt>
<dd>
<p>List, or view the folder's existence. If a folder
does not have the <span class="quote">“<span class="quote"><code class="literal">l</code></span>”</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">“<span class="quote"><code class="literal">r</code></span>”</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">“<span class="quote"><code class="literal">r</code></span>”</span></span></dt>
<dd>
<p>Read, or open the folder. An attempt to open the
folder will fail without the <span class="quote">“<span class="quote"><code class="literal">r</code></span>”</span> access right,
even if the folder's name is known.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">p</code></span>”</span></span></dt>
<dd>
<p><span class="quote">“<span class="quote">Post messages</span>”</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">“<span class="quote"><code class="literal">s</code></span>”</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">“<span class="quote"><code class="literal">s</code></span>”</span> access
right.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">t</code></span>”</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">“<span class="quote"><code class="literal">t</code></span>”</span> access
right.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">w</code></span>”</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">“<span class="quote"><code class="literal">w</code></span>”</span> access
right.</p>
</dd>
<dt><span class="term"><span class="quote">“<span class="quote"><code class="literal">x</code></span>”</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">“<span class="quote"><code class="literal">x</code></span>”</span> access
right.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2" title="Adding or removing access rights">
<a id="id641789" shape="rect" name="id641789"> </a>
<h3>Adding or removing access rights</h3>
<p>If <em class="replaceable"><code>rights</code></em>
begins with <span class="quote">“<span class="quote">+</span>”</span>, the remaining access rights
are added to any existing rights that <em class="replaceable"><code>identifier</code></em> already has. If
<em class="replaceable"><code>rights</code></em> begins
with <span class="quote">“<span class="quote">-</span>”</span>, the remaining access rights
are removed from <em class="replaceable"><code>identifier</code></em> existing access
rights.</p>
</div>
<div class="refsect2" title="Extended error reporting">
<a id="id641829" shape="rect" name="id641829"> </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">“<span class="quote">e</span>”</span>, <span class="quote">“<span class="quote">t</span>”</span>,
and <span class="quote">“<span class="quote">x</span>”</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" title="RETURN CODES AND CALLBACKS">
<a id="id641890" shape="rect" name="id641890"> </a>
<h2>RETURN CODES AND CALLBACKS</h2>
<p>The application must wait until <em class="parameter"><code>callback</code></em>'s <code class="function">success</code> or <code class="function">fail</code> method is invoked. The <code class="function">success</code> method is invoked when this request
is succesfully processed. The <code class="function">fail</code> method is invoked if this request
cannot be processed. The application must not destroy
<em class="parameter"><code>callback</code></em> until either
the <code class="function">success</code> or <code class="function">fail</code> method is invoked.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><em class="parameter"><code>callback</code></em>'s
<code class="function">fail</code> method may be invoked
even after other callback methods were invoked. This
indicates that the request was partially completed before
the error was encountered.</p>
</div>
</div>
<div class="refsect1" title="SEE ALSO">
<a id="id641979" shape="rect" name="id641979"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="folder-delrights.html" title="mail::folder::delRights" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::delRights</span>(3x)</span></a>,
<a class="link" href="folder-getmyrights.html" title="mail::folder::getMyRights" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getMyRights</span>(3x)</span></a>,
<a class="link" href="folder-getrights.html" title="mail::folder::getRights" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getRights</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="folder-renamefolder.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="libmail-folder.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="folder-tostring.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::folder::renameFolder </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::folder::toString</td>
</tr>
</table>
</div>
</body>
</html>
|