<refentry id="camel-CamelFolderSearch">
<refmeta>
<refentrytitle role="top_of_page" id="camel-CamelFolderSearch.top_of_page">CamelFolderSearch</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAMEL Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>CamelFolderSearch</refname>
<refpurpose></refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="camel-CamelFolderSearch.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
struct              <link linkend="CamelFolderSearch">CamelFolderSearch</link>;
<link linkend="CamelFolderSearch">CamelFolderSearch</link>*  <link linkend="camel-folder-search-new">camel_folder_search_new</link>             (void);
<link linkend="void">void</link>                <link linkend="camel-folder-search-construct">camel_folder_search_construct</link>       (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search);
<link linkend="void">void</link>                <link linkend="camel-folder-search-set-folder">camel_folder_search_set_folder</link>      (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="CamelFolder">CamelFolder</link> *folder);
<link linkend="void">void</link>                <link linkend="camel-folder-search-set-summary">camel_folder_search_set_summary</link>     (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="GPtrArray">GPtrArray</link> *summary);
<link linkend="void">void</link>                <link linkend="camel-folder-search-set-body-index">camel_folder_search_set_body_index</link>  (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="CamelIndex">CamelIndex</link> *index);
<link linkend="GPtrArray">GPtrArray</link>*          <link linkend="camel-folder-search-execute-expression">camel_folder_search_execute_expression</link>
                                                        (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         const <link linkend="char">char</link> *expr,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="GPtrArray">GPtrArray</link>*          <link linkend="camel-folder-search-search">camel_folder_search_search</link>          (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         const <link linkend="char">char</link> *expr,
                                                         <link linkend="GPtrArray">GPtrArray</link> *uids,
                                                         <link linkend="CamelException">CamelException</link> *ex);
<link linkend="void">void</link>                <link linkend="camel-folder-search-free-result">camel_folder_search_free_result</link>     (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="GPtrArray">GPtrArray</link> *);
</synopsis>
</refsynopsisdiv>









<refsect1 id="camel-CamelFolderSearch.description" role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="camel-CamelFolderSearch.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CamelFolderSearch" role="struct">
<title>struct CamelFolderSearch</title>
<indexterm zone="CamelFolderSearch"><primary>CamelFolderSearch</primary></indexterm><programlisting>struct CamelFolderSearch {
	CamelObject parent;

	struct _CamelFolderSearchPrivate *priv;

	ESExp *sexp;		/* s-exp evaluator */
	char *last_search;	/* last searched expression */

	/* these are only valid during the search, and are reset afterwards */
	CamelFolder *folder;	/* folder for current search */
	GPtrArray *summary;	/* summary array for current search */
	GPtrArray *summary_set;	/* subset of summary to actually include in search */

	GString *query; /* shall contain the SQL quer that should be executed */

// DEPRECATED	
//	GHashTable *summary_hash; /* hashtable of summary items */
	CamelMessageInfo *current; /* current message info, when searching one by one */
	CamelMimeMessage *current_message; /* cache of current message, if required */
	CamelIndex *body_index;
};
</programlisting>
<para>

</para></refsect2>
<refsect2 id="camel-folder-search-new" role="function">
<title>camel_folder_search_new ()</title>
<indexterm zone="camel-folder-search-new"><primary>camel_folder_search_new</primary></indexterm><programlisting><link linkend="CamelFolderSearch">CamelFolderSearch</link>*  camel_folder_search_new             (void);</programlisting>
<para>
Create a new CamelFolderSearch object.
</para>
<para>
A CamelFolderSearch is a subclassable, extensible s-exp
evaluator which enforces a particular set of s-expressions.
Particular methods may be overriden by an implementation to
implement a search for any sort of backend.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new CamelFolderSearch widget.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-folder-search-construct" role="function">
<title>camel_folder_search_construct ()</title>
<indexterm zone="camel-folder-search-construct"><primary>camel_folder_search_construct</primary></indexterm><programlisting><link linkend="void">void</link>                camel_folder_search_construct       (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>search</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-folder-search-set-folder" role="function">
<title>camel_folder_search_set_folder ()</title>
<indexterm zone="camel-folder-search-set-folder"><primary>camel_folder_search_set_folder</primary></indexterm><programlisting><link linkend="void">void</link>                camel_folder_search_set_folder      (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="CamelFolder">CamelFolder</link> *folder);</programlisting>
<para>
Set the folder attribute of the search.  This is currently unused, but
could be used to perform a slow-search when indexes and so forth are not
available.  Or for use by subclasses.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>search</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>folder</parameter>&nbsp;:</term>
<listitem><simpara> A folder.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-folder-search-set-summary" role="function">
<title>camel_folder_search_set_summary ()</title>
<indexterm zone="camel-folder-search-set-summary"><primary>camel_folder_search_set_summary</primary></indexterm><programlisting><link linkend="void">void</link>                camel_folder_search_set_summary     (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="GPtrArray">GPtrArray</link> *summary);</programlisting>
<para>
Set the array of summary objects representing the span of the search.
</para>
<para>
If this is not set, then a subclass must provide the functions
for searching headers and for the match-all operator.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>search</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>summary</parameter>&nbsp;:</term>
<listitem><simpara> An array of CamelMessageInfo pointers.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-folder-search-set-body-index" role="function">
<title>camel_folder_search_set_body_index ()</title>
<indexterm zone="camel-folder-search-set-body-index"><primary>camel_folder_search_set_body_index</primary></indexterm><programlisting><link linkend="void">void</link>                camel_folder_search_set_body_index  (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="CamelIndex">CamelIndex</link> *index);</programlisting>
<para>
Set the index representing the contents of all messages
in this folder.  If this is not set, then the folder implementation
should sub-class the CamelFolderSearch and provide its own
body-contains function.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>search</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-folder-search-execute-expression" role="function">
<title>camel_folder_search_execute_expression ()</title>
<indexterm zone="camel-folder-search-execute-expression"><primary>camel_folder_search_execute_expression</primary></indexterm><programlisting><link linkend="GPtrArray">GPtrArray</link>*          camel_folder_search_execute_expression
                                                        (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         const <link linkend="char">char</link> *expr,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Execute the search expression <parameter>expr</parameter>, returning an array of
all matches as a GPtrArray of uid's of matching messages.
</para>
<para>
Note that any settings such as <link linkend="set-body-index"><function>set_body_index()</function></link>, <link linkend="set-folder"><function>set_folder()</function></link>,
and so on are reset to <link linkend="NULL:CAPS"><type>NULL</type></link> once the search has completed.
</para>
<para>
TODO: The interface should probably return summary items instead
(since they are much more useful to any client).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>search</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>expr</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A GPtrArray of strings of all matching messages.
This must only be freed by camel_folder_search_free_result.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-folder-search-search" role="function">
<title>camel_folder_search_search ()</title>
<indexterm zone="camel-folder-search-search"><primary>camel_folder_search_search</primary></indexterm><programlisting><link linkend="GPtrArray">GPtrArray</link>*          camel_folder_search_search          (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         const <link linkend="char">char</link> *expr,
                                                         <link linkend="GPtrArray">GPtrArray</link> *uids,
                                                         <link linkend="CamelException">CamelException</link> *ex);</programlisting>
<para>
Run a search.  Search must have had Folder already set on it, and
it must implement summaries.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>search</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>expr</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uids</parameter>&nbsp;:</term>
<listitem><simpara> to search against, NULL for all uid's.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ex</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-folder-search-free-result" role="function">
<title>camel_folder_search_free_result ()</title>
<indexterm zone="camel-folder-search-free-result"><primary>camel_folder_search_free_result</primary></indexterm><programlisting><link linkend="void">void</link>                camel_folder_search_free_result     (<link linkend="CamelFolderSearch">CamelFolderSearch</link> *search,
                                                         <link linkend="GPtrArray">GPtrArray</link> *);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>search</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>Param2</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
