<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::ACCOUNT::searchMessages</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-savefolderindexinfo.html" title="mail::ACCOUNT::saveFolderIndexInfo"/>
<link rel="next" href="account-send.html" title="mail::ACCOUNT::send"/>
<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::searchMessages</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="account-savefolderindexinfo.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-send.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="account-searchmessages" shape="rect" name="account-searchmessages"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::ACCOUNT::searchMessages — Search messages in
the current folder</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"/>
#include <libmail/search.H><br clear="none"/>
<br clear="none"/>
mail::ACCOUNT *mail;<br clear="none"/>
<br clear="none"/>
<br clear="none"/>
<br clear="none"/>
mail::searchParams mySearchParams;<br clear="none"/>
<br clear="none"/>
mySearchParams.criteria=<em class="replaceable"><code>criteria</code></em>;<br clear="none"/>
mySearchParams.searchNot=<em class="replaceable"><code>notFlag</code></em>;<br clear="none"/>
mySearchParams.param1="<em class="replaceable"><code>text</code></em>";<br clear="none"/>
mySearchParams.param2="<em class="replaceable"><code>text</code></em>";<br clear="none"/>
mySearchParams.charset="<em class="replaceable"><code>text</code></em>";<br clear="none"/>
mySearchParams.scope=<em class="replaceable"><code>scope</code></em>;<br clear="none"/>
<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">searchMessages</b>(</code></td>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1"><var class="pdparam">mySearchParams</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">std::vector<size_t>
& </td>
<td rowspan="1" colspan="1"><var class="pdparam">messageList</var><code>)</code>;</td>
</tr>
</table>
</div>
<div class="literallayout">
<p><br clear="none"/>
std::string errmsg=mail->getErrmsg();<br clear="none"/></p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id573516" shape="rect" name="id573516"> </a>
<h2>USAGE</h2>
<p><code class="function">mail::ACCOUNT::searchMessages</code> searches
messages in the currently-open folder. <em class="parameter"><code>messageList</code></em> should be an empty
array. Message numbers of messages found by the search are
added to the array.</p>
<p><em class="structfield"><code>mySearchParams.criteria</code></em>
specifies the search type. <em class="structfield"><code>mySearchParams.searchNot</code></em> is a
bool; setting it to <code class="literal">true</code>
logically negates the search type. For example, if <em class="structfield"><code>mySearchParams.criteria</code></em> is
<code class="literal">mail::searchParams::on</code> then
setting <em class="structfield"><code>mySearchParams.searchNot</code></em> to
<code class="literal">true</code> will search for messages
NOT sent on the specified date.</p>
<p><em class="structfield"><code>mySearchParams.param1</code></em> and
<em class="structfield"><code>mySearchParams.param2</code></em> specify
additional parameters used by some search criterias.
<em class="structfield"><code>mySearchParams.charset</code></em>
specifies <em class="structfield"><code>mySearchParams.param2</code></em>'s
character set. <em class="structfield"><code>mySearchParams.param1</code></em>'s
character set is always <code class="literal">ISO-8859-1</code>.</p>
<p><em class="structfield"><code>mySearchParams.scope</code></em>
specifies the scope of the search, and must be set to one of
the following:</p>
<div class="variablelist">
<p>Complex search criteria may be performed as follows:</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>Clear <em class="structfield"><code>mail::messageInfo::marked</code></em>
status flags on all messages (use <a class="link" href="mail-updatefolderindexflags.html" title="mail::account::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::updateFolderIndexFlags</span>(3x)</span></a>
or <a class="link" href="account-updatefolderindexflags.html" title="mail::ACCOUNT::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::updateFolderIndexFlags</span>(3x)</span></a>.</p>
</li>
<li>
<p>Execute a search with <em class="structfield"><code>mySearchParams.scope</code></em>
set to <code class="literal">search_unmarked</code>.</p>
</li>
<li>
<p>Use <a class="link" href="mail-updatefolderindexflags.html" title="mail::account::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::updateFolderIndexFlags</span>(3x)</span></a>
or <a class="link" href="account-updatefolderindexflags.html" title="mail::ACCOUNT::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::updateFolderIndexFlags</span>(3x)</span></a>
to set the <em class="structfield"><code>mail::messageInfo::marked</code></em>
flag on messages found by the first search.</p>
</li>
<li>
<p>Run additional searches, with <em class="structfield"><code>mySearchParams.scope</code></em>
set accordingly; and use <a class="link" href="mail-updatefolderindexflags.html" title="mail::account::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::updateFolderIndexFlags</span>(3x)</span></a>
or <a class="link" href="account-updatefolderindexflags.html" title="mail::ACCOUNT::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::updateFolderIndexFlags</span>(3x)</span></a>
to set or reset the <em class="structfield"><code>mail::messageInfo::marked</code></em>
flag on messages found by the search.</p>
</li>
</ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The <em class="structfield"><code>mail::messageInfo::marked</code></em>
status flag's usage is not limited to searches.
<em class="structfield"><code>mail::messageInfo::marked</code></em>
is a generic flag that applications may use for their own
purposes. Searching is one such particular application
for this flag.</p>
<p>Some IMAP servers do not implemented the <em class="structfield"><code>mail::messageInfo::marked</code></em>
status flag, and there's no such thing as a status flag
in the POP3 protocol. When <em class="structfield"><code>mail::messageInfo::marked</code></em>
status flag is not implemented by the server,
<span class="structname">mail::account</span> will
synthesize a suitable replacement that will work just
like the real thing (except that the status flags of
messages will not be saved when the folder is
closed).</p>
</div>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id574201" shape="rect" name="id574201"> </a>
<h3>Search Criteria</h3>
<p><em class="structfield"><code>mySearchParams.criteria</code></em>
must be set to one of the following constants:</p>
<div class="variablelist">
<dl>
<dt><span class="term">mail::searchParams::replied</span></dt>
<dd>
<p>Search for messages with the <em class="structfield"><code>mail::messageInfo::replied</code></em>
status flag set.</p>
</dd>
<dt><span class="term">mail::searchParams::deleted</span></dt>
<dd>
<p>Search for messages with the <em class="structfield"><code>mail::messageInfo::deleted</code></em>
status flag set.</p>
</dd>
<dt><span class="term">mail::searchParams::draft</span></dt>
<dd>
<p>Search for messages with the <em class="structfield"><code>mail::messageInfo::draft</code></em>
status flag set.</p>
</dd>
<dt><span class="term">mail::searchParams::unread</span></dt>
<dd>
<p>Search for messages with the <em class="structfield"><code>mail::messageInfo::unread</code></em>
status flag set.</p>
</dd>
<dt><span class="term">mail::searchParams::from</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in their <code class="literal">From:</code>
header.</p>
</dd>
<dt><span class="term">mail::searchParams::to</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in their <code class="literal">To:</code>
header.</p>
</dd>
<dt><span class="term">mail::searchParams::cc</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in their <code class="literal">Cc:</code>
header.</p>
</dd>
<dt><span class="term">mail::searchParams::bcc</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in their <code class="literal">Bcc:</code>
header.</p>
</dd>
<dt><span class="term">mail::searchParams::subject</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in their <code class="literal">Subject:</code> header.</p>
</dd>
<dt><span class="term">mail::searchParams::header</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in a header whose name is <em class="structfield"><code>mail::searchParams.param1</code></em>.</p>
</dd>
<dt><span class="term">mail::searchParams::body</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in the message's contents.</p>
</dd>
<dt><span class="term">mail::searchParams::text</span></dt>
<dd>
<p>Search for messages where <em class="structfield"><code>mail::searchParams.param2</code></em>
occurs in the message's contents or headers.</p>
</dd>
<dt><span class="term">mail::searchParams::before</span></dt>
<dd>
<p>Search for messages received before the date
specified by <em class="structfield"><code>mail::searchParams.param2</code></em>.</p>
</dd>
<dt><span class="term">mail::searchParams::on</span></dt>
<dd>
<p>Search for messages received on the date
specified by <em class="structfield"><code>mail::searchParams.param2</code></em>.</p>
</dd>
<dt><span class="term">mail::searchParams::since</span></dt>
<dd>
<p>Search for messages received on or after the
date specified by <em class="structfield"><code>mail::searchParams.param2</code></em>.</p>
</dd>
<dt><span class="term">mail::searchParams::sentbefore</span></dt>
<dd>
<p>Search for messages whose <code class="literal">Date:</code> header contains a date
before the date specified by <em class="structfield"><code>mail::searchParams.param2</code></em>.</p>
</dd>
<dt><span class="term">mail::searchParams::senton</span></dt>
<dd>
<p>Search for messages whose <code class="literal">Date:</code> header contains a date
specified by <em class="structfield"><code>mail::searchParams.param2</code></em>.</p>
</dd>
<dt><span class="term">mail::searchParams::sentsince</span></dt>
<dd>
<p>Search for messages whose <code class="literal">Date:</code> header contains a date
specified by <em class="structfield"><code>mail::searchParams.param2</code></em>,
or later.</p>
</dd>
<dt><span class="term">mail::searchParams::larger</span></dt>
<dd>
<p>Search for messages whose approximate size is at
least as the number of bytes specified by
<em class="structfield"><code>mail::searchParams.param2</code></em>.</p>
</dd>
<dt><span class="term">mail::searchParams::smaller</span></dt>
<dd>
<p>Search for messages whose approximate size is
less than the number of bytes specified by
<em class="structfield"><code>mail::searchParams.param2</code></em>.</p>
</dd>
</dl>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><em class="structfield"><code>mail::searchParams.param2</code></em>
contains a text string of the form "mm-ddd-yyyy" for
date-related search criteria (example: <code class="literal">"12-Oct-2001"</code>).</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Usenet servers offer very limited searching
facilities. Consequently, searching NetNews folders
will be slow, and inefficient. Searching on status
flags is reasonably fast, since <span class="application">LibMAIL</span> maintains status flags of
NetNews folders internally. The following search
parameters use the <code class="literal">NNTP
XPAT</code> command, provides that the search string
uses only the <code class="literal">US-ASCII</code>
alphabet, and will also be reasonably fast:
<code class="literal">mail::searchParams::from</code>,
<code class="literal">mail::searchParams::to</code>,
<code class="literal">mail::searchParams::cc</code>,
<code class="literal">mail::searchParams::bcc</code>,
<code class="literal">mail::searchParams::subject</code>, and
<code class="literal">mail::searchParams::header</code>.</p>
<p>For all other searches, or if the search string uses
characters outside of the <code class="literal">US-ASCII</code> character set, <span class="application">LibMAIL</span> will download each message
individually, in order to search it. That's going to be
very, very slow.</p>
<p>Additionally, most Usenet servers's <code class="literal">NNTP XPAT</code> is case sensitive. All other
searches are case insensitive.</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Efficient searching is implemented for local mail,
and IMAP/SMAP mailboxes only. NetNews servers'
searching capabilities are very limited, and POP3
servers have no search facilities whatsoever. In all
cases, searching for message status flags is supported,
since message status flags are always cached
locally.</p>
<p>Only message headers of NetNews folders may be
searched, and only English characters can be used as a
search string. Some older NetNews servers may not have
any searching ability whatsoever. Searching of message
contents is not supported. Searching by message size,
or message's date is not supported either.</p>
<p>Searching of POP3 folders is also not very
efficient, although the search text is not limited to
English characters only. POP3 folder search is
accomplished by downloading the complete headers of
each message, and searching it manually. Downloaded
headers are not cached. The headers are also downloaded
when searching by message's date. Searching by message
size, or message's date is not supported for POP3
folders.</p>
</div>
</div>
<dl>
<dt><span class="term">search_all</span></dt>
<dd>
<p>Search all messages in the folder.</p>
</dd>
<dt><span class="term">search_marked</span></dt>
<dd>
<p>Search only messages that have <em class="structfield"><code>mail::messageInfo::marked</code></em>
set to <code class="literal">true</code>.</p>
</dd>
<dt><span class="term">search_unmarked</span></dt>
<dd>
<p>Search only messages that have <em class="structfield"><code>mail::messageInfo::marked</code></em>
set to <code class="literal">false</code>.</p>
</dd>
<dt><span class="term">search_ranges</span></dt>
<dd>
<p>Search only message #<em class="structfield"><code>rangeLo</code></em> through message
#<em class="structfield"><code>rangeHi</code></em>-1.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id575431" shape="rect" name="id575431"> </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="id575467" shape="rect" name="id575467"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="account-copymessagesto.html" title="mail::ACCOUNT::copyMessagesTo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::copyMessagesTo</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-savefolderindexinfo.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-send.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::ACCOUNT::saveFolderIndexInfo </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::send</td>
</tr>
</table>
</div>
</body>
</html>
