<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="synchronous.html" title="mail::ACCOUNT Synchronous API reference"/> <link rel="prev" href="account-updatefolderindexinfo.html" title="mail::ACCOUNT::updateFolderIndexInfo"/> <link rel="next" href="native.html" title="mail::account Native API reference"/> <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="account-updatefolderindexinfo.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="native.html" shape="rect">Next</a></td> </tr> </table> <hr/> </div> <div class="refentry" lang="en" xml:lang="en"> <a id="account-updatekeywords" shape="rect" name="account-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/sync.H><br clear="none"/> <br clear="none"/> mail::ACCOUNT *mail;<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">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><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">bool ok=mail-><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><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">bool ok=mail-><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><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en" xml:lang="en"> <a id="id583011" shape="rect" name="id583011"> </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).</p> <p><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="account-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. When a message is removed from the folder, by <a class="link" href="account-updatefolderindexinfo.html" title="mail::ACCOUNT::updateFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::updateFolderIndexInfo</span>(3x)</span></a>, the following messages are renumbered accordingly.</p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p>Most mail servers allow multiple applications to open the same folder. Therefore, changes to the folder's contents can occur at any time. Before making this request, the application should use <a class="link" href="account-checknewmail.html" title="mail::ACCOUNT::checkNewMail" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::checkNewMail</span>(3x)</span></a> to verify that no unexpected changes have been made to the folder's contents.</p> </div> <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="id583514" shape="rect" name="id583514"> </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="id583338" shape="rect" name="id583338"> </a> <h2>Return Codes</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="id583374" shape="rect" name="id583374"> </a> <h2>SEE ALSO</h2> <p><a class="link" href="account-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="account-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="account-getfolderkeywordinfo.html" title="mail::ACCOUNT::getFolderKeywordInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::getFolderKeywordInfo</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-updatefolderindexinfo.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="native.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"> <span class="structname">mail::account</span> Native API reference</td> </tr> </table> </div> </body> </html>