<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libebook-e-book-query">
<refmeta>
<refentrytitle role="top_of_page">e-book-query</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBEBOOK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>e-book-query</refname>
<refpurpose>Handles queries of addressboook data.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>



typedef     <link linkend="EBookQuery">EBookQuery</link>;
enum        <link linkend="EBookQueryTest">EBookQueryTest</link>;
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-from-string">e_book_query_from_string</link>        (const <link linkend="char">char</link> *query_string);
<link linkend="char">char</link>*       <link linkend="e-book-query-to-string">e_book_query_to_string</link>          (<link linkend="EBookQuery">EBookQuery</link> *q);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-ref">e_book_query_ref</link>                (<link linkend="EBookQuery">EBookQuery</link> *q);
<link linkend="void">void</link>        <link linkend="e-book-query-unref">e_book_query_unref</link>              (<link linkend="EBookQuery">EBookQuery</link> *q);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-and">e_book_query_and</link>                (<link linkend="int">int</link> nqs,
                                             <link linkend="EBookQuery">EBookQuery</link> **qs,
                                             <link linkend="gboolean">gboolean</link> unref);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-andv">e_book_query_andv</link>               (<link linkend="EBookQuery">EBookQuery</link> *q,
                                             ...);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-or">e_book_query_or</link>                 (<link linkend="int">int</link> nqs,
                                             <link linkend="EBookQuery">EBookQuery</link> **qs,
                                             <link linkend="gboolean">gboolean</link> unref);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-orv">e_book_query_orv</link>                (<link linkend="EBookQuery">EBookQuery</link> *q,
                                             ...);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-not">e_book_query_not</link>                (<link linkend="EBookQuery">EBookQuery</link> *q,
                                             <link linkend="gboolean">gboolean</link> unref);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-field-exists">e_book_query_field_exists</link>       (<link linkend="EContactField">EContactField</link> field);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-vcard-field-exists">e_book_query_vcard_field_exists</link> (const <link linkend="char">char</link> *field);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-field-test">e_book_query_field_test</link>         (<link linkend="EContactField">EContactField</link> field,
                                             <link linkend="EBookQueryTest">EBookQueryTest</link> test,
                                             const <link linkend="char">char</link> *value);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-any-field-contains">e_book_query_any_field_contains</link> (const <link linkend="char">char</link> *value);
<link linkend="EBookQuery">EBookQuery</link>* <link linkend="e-book-query-copy">e_book_query_copy</link>               (<link linkend="EBookQuery">EBookQuery</link> *q);

</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="EBookQuery" role="typedef"/>EBookQuery</title>
<indexterm><primary>EBookQuery</primary></indexterm><programlisting>typedef struct EBookQuery EBookQuery;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="EBookQueryTest" role="enum"/>enum EBookQueryTest</title>
<indexterm><primary>EBookQueryTest</primary></indexterm><programlisting>typedef enum {
  E_BOOK_QUERY_IS,
  E_BOOK_QUERY_CONTAINS,
  E_BOOK_QUERY_BEGINS_WITH,
  E_BOOK_QUERY_ENDS_WITH,

  /*
    Consider these "coming soon". 

    E_BOOK_QUERY_LT,
    E_BOOK_QUERY_LE,
    E_BOOK_QUERY_GT,
    E_BOOK_QUERY_GE,
    E_BOOK_QUERY_EQ,
  */
} EBookQueryTest;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="e-book-query-from-string" role="function"/>e_book_query_from_string ()</title>
<indexterm><primary>e_book_query_from_string</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_from_string        (const <link linkend="char">char</link> *query_string);</programlisting>
<para>
Parse <parameter>query_string</parameter> and return a new <link linkend="EBookQuery"><type>EBookQuery</type></link> representing it.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>query_string</parameter>&nbsp;:</term>
<listitem><simpara> the query
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="EBookValue"><type>EBookValue</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-to-string" role="function"/>e_book_query_to_string ()</title>
<indexterm><primary>e_book_query_to_string</primary></indexterm><programlisting><link linkend="char">char</link>*       e_book_query_to_string          (<link linkend="EBookQuery">EBookQuery</link> *q);</programlisting>
<para>
Return the string representation of <parameter>q</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>q</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The string form of the query. This string should be freed when
finished with.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-ref" role="function"/>e_book_query_ref ()</title>
<indexterm><primary>e_book_query_ref</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_ref                (<link linkend="EBookQuery">EBookQuery</link> *q);</programlisting>
<para>
Increment the reference count on <parameter>q</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>q</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <parameter>q</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-unref" role="function"/>e_book_query_unref ()</title>
<indexterm><primary>e_book_query_unref</primary></indexterm><programlisting><link linkend="void">void</link>        e_book_query_unref              (<link linkend="EBookQuery">EBookQuery</link> *q);</programlisting>
<para>
Decrement the reference count on <parameter>q</parameter>. When the reference count reaches 0, <parameter>q</parameter>
will be freed and any child queries will have <link linkend="e-book-query-unref"><function>e_book_query_unref()</function></link> called.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>q</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-and" role="function"/>e_book_query_and ()</title>
<indexterm><primary>e_book_query_and</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_and                (<link linkend="int">int</link> nqs,
                                             <link linkend="EBookQuery">EBookQuery</link> **qs,
                                             <link linkend="gboolean">gboolean</link> unref);</programlisting>
<para>
Create a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which is the logical AND of the queries in <link linkend="qs"><type>qs</type></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>nqs</parameter>&nbsp;:</term>
<listitem><simpara> the number of queries to AND
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>qs</parameter>&nbsp;:</term>
<listitem><simpara> pointer to an array of <link linkend="EBookQuery"><type>EBookQuery</type></link> items
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>unref</parameter>&nbsp;:</term>
<listitem><simpara> if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, the new query takes ownership of the existing queries
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-andv" role="function"/>e_book_query_andv ()</title>
<indexterm><primary>e_book_query_andv</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_andv               (<link linkend="EBookQuery">EBookQuery</link> *q,
                                             ...);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which is the logical AND of the queries specified.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>q</parameter>&nbsp;:</term>
<listitem><simpara> first <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="NULL:CAPS"><type>NULL</type></link> terminated list of <link linkend="EBookQuery"><type>EBookQuery</type></link> pointers
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-or" role="function"/>e_book_query_or ()</title>
<indexterm><primary>e_book_query_or</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_or                 (<link linkend="int">int</link> nqs,
                                             <link linkend="EBookQuery">EBookQuery</link> **qs,
                                             <link linkend="gboolean">gboolean</link> unref);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which is the logical OR of the queries in <link linkend="qs"><type>qs</type></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>nqs</parameter>&nbsp;:</term>
<listitem><simpara> the number of queries to OR
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>qs</parameter>&nbsp;:</term>
<listitem><simpara> pointer to an array of <link linkend="EBookQuery"><type>EBookQuery</type></link> items
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>unref</parameter>&nbsp;:</term>
<listitem><simpara> if <link linkend="TRUE:CAPS"><type>TRUE</type></link>, the new query takes ownership of the existing queries
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-orv" role="function"/>e_book_query_orv ()</title>
<indexterm><primary>e_book_query_orv</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_orv                (<link linkend="EBookQuery">EBookQuery</link> *q,
                                             ...);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which is the logical OR of the queries specified.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>q</parameter>&nbsp;:</term>
<listitem><simpara> first <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="NULL:CAPS"><type>NULL</type></link> terminated list of <link linkend="EBookQuery"><type>EBookQuery</type></link> pointers
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-not" role="function"/>e_book_query_not ()</title>
<indexterm><primary>e_book_query_not</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_not                (<link linkend="EBookQuery">EBookQuery</link> *q,
                                             <link linkend="gboolean">gboolean</link> unref);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which is the opposite of <link linkend="q"><type>q</type></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>q</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>unref</parameter>&nbsp;:</term>
<listitem><simpara> if <link linkend="TRUE:CAPS"><type>TRUE</type></link>, the new query takes ownership of the existing queries
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-field-exists" role="function"/>e_book_query_field_exists ()</title>
<indexterm><primary>e_book_query_field_exists</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_field_exists       (<link linkend="EContactField">EContactField</link> field);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which tests if the field <parameter>field</parameter> exists.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>field</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="EContactField"><type>EContactField</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-vcard-field-exists" role="function"/>e_book_query_vcard_field_exists ()</title>
<indexterm><primary>e_book_query_vcard_field_exists</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_vcard_field_exists (const <link linkend="char">char</link> *field);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which tests if the field <parameter>field</parameter> exists. <parameter>field</parameter>
should be a vCard field name, such as <link linkend="FN:CAPS"><type>FN</type></link> or <link linkend="X-MSN:CAPS"><type>X-MSN</type></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>field</parameter>&nbsp;:</term>
<listitem><simpara> a field name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-field-test" role="function"/>e_book_query_field_test ()</title>
<indexterm><primary>e_book_query_field_test</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_field_test         (<link linkend="EContactField">EContactField</link> field,
                                             <link linkend="EBookQueryTest">EBookQueryTest</link> test,
                                             const <link linkend="char">char</link> *value);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which tests <parameter>field</parameter> for <parameter>value</parameter> using the test <parameter>test</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>field</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EContactField"><type>EContactField</type></link> to test
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test</parameter>&nbsp;:</term>
<listitem><simpara> the test to apply
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
<listitem><simpara> the value to test for
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-any-field-contains" role="function"/>e_book_query_any_field_contains ()</title>
<indexterm><primary>e_book_query_any_field_contains</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_any_field_contains (const <link linkend="char">char</link> *value);</programlisting>
<para>
Creates a new <link linkend="EBookQuery"><type>EBookQuery</type></link> which tests if any field contains <parameter>value</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
<listitem><simpara> a value
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="EBookQuery"><type>EBookQuery</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-book-query-copy" role="function"/>e_book_query_copy ()</title>
<indexterm><primary>e_book_query_copy</primary></indexterm><programlisting><link linkend="EBookQuery">EBookQuery</link>* e_book_query_copy               (<link linkend="EBookQuery">EBookQuery</link> *q);</programlisting>
<para>

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


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

</refsect1>




</refentry>
