<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::account::updateKeywords</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="native.html" title="mail::account Native API reference"/>
<link rel="prev" href="mail-updatefolderindexinfo.html" title="mail::account::updateFolderIndexInfo"/>
<link rel="next" href="mail-updatenotify.html" title="mail::account::updateNotify"/>
<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::updateKeywords</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="mail-updatefolderindexinfo.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
<span class="structname">mail::account</span> Native API
reference</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="mail-updatenotify.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="mail-updatekeywords" shape="rect" name="mail-updatekeywords"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::account::updateKeywords — Update message
keywords</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/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="literallayout">
<p><br clear="none"/>
mail::account *account;<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">account-><b class="fsfunc">updateKeywords</b>(</code></td>
<td rowspan="1" colspan="1">const
std::vector<size_t>  </td>
<td rowspan="1" colspan="1"><var class="pdparam">msgList</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">const
std::set<std::string> & </td>
<td rowspan="1" colspan="1"><var class="pdparam">keywords</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">bool  </td>
<td rowspan="1" colspan="1"><var class="pdparam">setOrChange</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">bool  </td>
<td rowspan="1" colspan="1"><var class="pdparam">changeTo</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myCallback & </td>
<td rowspan="1" colspan="1"><var class="pdparam">callback</var><code>)</code>;</td>
</tr>
</table>
</div>
<div class="funcsynopsis">
<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
<tr>
<td rowspan="1" colspan="1"><code class="funcdef">account-><b class="fsfunc">updateKeywords</b>(</code></td>
<td rowspan="1" colspan="1">const
std::vector<size_t>  </td>
<td rowspan="1" colspan="1"><var class="pdparam">msgList</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">const
std::list<std::string> & </td>
<td rowspan="1" colspan="1"><var class="pdparam">keywords</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">bool  </td>
<td rowspan="1" colspan="1"><var class="pdparam">setOrChange</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">bool  </td>
<td rowspan="1" colspan="1"><var class="pdparam">changeTo</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myCallback & </td>
<td rowspan="1" colspan="1"><var class="pdparam">callback</var><code>)</code>;</td>
</tr>
</table>
</div>
<div class="funcsynopsis">
<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
<tr>
<td rowspan="1" colspan="1"><code class="funcdef">account-><b class="fsfunc">updateKeywords</b>(</code></td>
<td rowspan="1" colspan="1">const
std::vector<size_t>  </td>
<td rowspan="1" colspan="1"><var class="pdparam">msgList</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">const
std::vector<std::string> & </td>
<td rowspan="1" colspan="1"><var class="pdparam">keywords</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">bool  </td>
<td rowspan="1" colspan="1"><var class="pdparam">setOrChange</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">bool  </td>
<td rowspan="1" colspan="1"><var class="pdparam">changeTo</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myCallback & </td>
<td rowspan="1" colspan="1"><var class="pdparam">callback</var><code>)</code>;</td>
</tr>
</table>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id610033" shape="rect" name="id610033"> </a>
<h2>USAGE</h2>
<p>This function updates the set of keywords of one or more
messages. <em class="parameter"><code>keywords</code></em>
may also be specified as a list, or a vector (and duplicate
occurences of a keyword are automatically removed).
<em class="parameter"><code>msgList</code></em> specifies a
list of messages. Messages are numbered starting with message
#0 and up to one less than <a class="link" href="mail-getfolderindexsize.html" title="mail::account::getFolderIndexSize" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexSize</span>(3x)</span></a>()
(when <code class="function">mail::account::getFolderIndexSize</code> returns
6, the messages are numbered 0 through 5). Only the messages
that appear in <em class="parameter"><code>msgList</code></em> are processed by this
request.</p>
<p>When <em class="parameter"><code>setOrChange</code></em>
is <code class="literal">false</code>, <em class="parameter"><code>changeTo</code></em> is ignored, and any
existing keywords set for each message in <em class="parameter"><code>msgList</code></em> are completely replaced
by <em class="parameter"><code>keywords</code></em>. When
<em class="parameter"><code>setOrChange</code></em> is
<code class="literal">true</code> <em class="parameter"><code>changeTo</code></em> selects whether
<em class="parameter"><code>keywords</code></em> are added to
the existing set of keywords that are already set for each
message (<em class="parameter"><code>changeTo</code></em> is
<code class="literal">true</code>), or removed from the
existing set of keywords (<em class="parameter"><code>changeTo</code></em> is <code class="literal">false</code>).</p>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id583162" shape="rect" name="id583162"> </a>
<h3>Keywords</h3>
<p>Keywords are application-defined flags, or markers, that
are associated which each message in a folder. Keywords
names are arbitrary, and are subject to certain
restrictions. <span class="application">LibMAIL</span> does
not place any special meaning on any particular keyword
name. <span class="application">LibMAIL</span> 's sole
involvement is to store the save the list of keywords set
for a given message, and then retrieve it upon demand.</p>
<p>Which characters may be included in a keyword name
depends on the underlying account type. Applications that
expect to use any supported account type should limit
themselves to the lowest common denominator: case
insensitive <code class="literal">us-ascii</code> character
set; no whitespace or any of the following characters:
commas; apostrophes; quotes; backslashes; forward slashes;
opening/closing braces, brackets, and parenthesis; question
marks; asterisks; percent signs. In all cases, keyword
names may not include any control characters. Unless
keywords are permanently saved, and remain available after
the folder is closed, and subsequently reopened. When the
folder is reopened at some point later, all keywords will
remain set for their corresponding messages (unless they
were modified by another process).</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>Temporary folders do not implement keywords.</p>
</li>
<li>
<p>IMAP accounts have case-insensitive keywords in
the <code class="literal">us-ascii</code> character
set. Keyword names may not contain: apostrophes;
quotes; backslashes; forward slashes; opening/closing
braces, brackets, and parenthesis; question marks;
asterisks; and percent signs.</p>
</li>
<li>
<p><a class="link" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1" shape="rect">SMAP</a> accounts have case-sensitive
keywords that use the <code class="literal">UTF-8</code> character set. Keyword names
may not contain commas.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>IMAP restrictions also apply if the same account
is accessible via IMAP.</p>
</div>
</li>
<li>
<p>Maildir accounts have case-sensitive keywords that
use the <code class="literal">UTF-8</code> character
set.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>IMAP and/or SMAP restrictions also apply if the
maildir is also accessible via IMAP or SMAP.</p>
</div>
</li>
<li>
<p>Mbox accounts have case-sensitive keywords that
use the <code class="literal">UTF-8</code> character
set.</p>
</li>
<li>
<p>NNTP and POP3 accounts have case-sensitive
keywords that use the <code class="literal">UTF-8</code> character set. Keywords are
not saved. When the folder is closed, all set
keywords are lost. Snapshots may be used to obtain
permanent keyword storage for NNTP and POP3 accounts.
See <a class="link" href="folder-open.html" title="mail::folder::open" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::open</span>(3x)</span></a>
for more information.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id610363" shape="rect" name="id610363"> </a>
<h2>Return Codes</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" 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 class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The application is notified about when a message's
status changes by by invoking the <code class="function">messageChanged</code> callback method of the
currently opened folder's <span class="structname">mail::folderCallback</span> object. Depending
on the mail server, the <code class="function">messageChanged</code> method may be invoked as
part of processing this request, or some time later after
this request is completed, and <em class="parameter"><code>callback</code></em>'s <code class="function">success</code> method was invoked.</p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id610501" shape="rect" name="id610501"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="mail-savefolderindexinfo.html" title="mail::account::saveFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::saveFolderIndexInfo</span>(3x)</span></a>,
<a class="link" href="mail-getfolderindexinfo.html" title="mail::account::getFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexInfo</span>(3x)</span></a>,
<a class="link" href="mail-getfolderkeywordinfo.html" title="mail::account::getFolderKeywordInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderKeywordInfo</span>(3x)</span></a>,
<a class="link" href="folder-open.html" title="mail::folder::open" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::open</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="mail-updatefolderindexinfo.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="native.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="mail-updatenotify.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::account::updateFolderIndexInfo </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::updateNotify</td>
</tr>
</table>
</div>
</body>
</html>
