## e-book-query e-book-query — Handles queries of addressboook data. |

## Synopsis

    typedef             EBookQuery;
    enum                EBookQueryTest;
    EBookQuery*         e_book_query_from_string            (const char *query_string);
    char*               e_book_query_to_string              (EBookQuery *q);
    EBookQuery*         e_book_query_ref                    (EBookQuery *q);
    void                e_book_query_unref                  (EBookQuery *q);
    EBookQuery*         e_book_query_and                    (int nqs,
                                                             EBookQuery **qs,
                                                             gboolean unref);
    EBookQuery*         e_book_query_andv                   (EBookQuery *q,
                                                             ...);
    EBookQuery*         e_book_query_or                     (int nqs,
                                                             EBookQuery **qs,
                                                             gboolean unref);
    EBookQuery*         e_book_query_orv                    (EBookQuery *q,
                                                             ...);
    EBookQuery*         e_book_query_not                    (EBookQuery *q,
                                                             gboolean unref);
    EBookQuery*         e_book_query_field_exists           (EContactField field);
    EBookQuery*         e_book_query_vcard_field_exists     (const char *field);
    EBookQuery*         e_book_query_field_test             (EContactField field,
                                                             EBookQueryTest test,
                                                             const char *value);
    EBookQuery*         e_book_query_vcard_field_test       (const char *field,
                                                             EBookQueryTest test,
                                                             const char *value);
    EBookQuery*         e_book_query_any_field_contains     (const char *value);
    EBookQuery*         e_book_query_copy                   (EBookQuery *q);

## Description

## Details

### EBookQuery

    typedef struct EBookQuery EBookQuery;

### enum EBookQueryTest

    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;

### e_book_query_from_string ()

    EBookQuery*         e_book_query_from_string            (const char *query_string);

Parse `query_string` and return a new EBookQuery representing it.

`query_string` : | the query
Returns : | the new EBookQuery.

### e_book_query_to_string ()

    char*               e_book_query_to_string              (EBookQuery *q);

Return the string representation of `q`.

`q` : | an EBookQuery
Returns : | The string form of the query. This string should be freed when finished with.

### e_book_query_ref ()

    EBookQuery*         e_book_query_ref                    (EBookQuery *q);

Increment the reference count on `q`.

`q` : | a EBookQuery
Returns : | `q`

### e_book_query_unref ()

    void                e_book_query_unref                  (EBookQuery *q);

Decrement the reference count on `q`. When the reference count reaches 0, `q` will be freed and any child queries will have `e_book_query_unref()` called.

`q` : | an EBookQuery

### e_book_query_and ()

    EBookQuery*         e_book_query_and                    (int nqs,
                                                             EBookQuery **qs,
                                                             gboolean unref);

Create a new EBookQuery which is the logical AND of the queries in qs.

`nqs` : | the number of queries to AND
`qs` : | pointer to an array of EBookQuery items
`unref` : | if `TRUE`, the new query takes ownership of the existing queries
Returns : | A new EBookQuery

### e_book_query_andv ()

    EBookQuery*         e_book_query_andv                   (EBookQuery *q,
                                                             ...);

Creates a new EBookQuery which is the logical AND of the queries specified.

`q` : | first EBookQuery
`...` : | NULL terminated list of EBookQuery pointers
Returns : | A new EBookQuery

### e_book_query_or ()

    EBookQuery*         e_book_query_or                     (int nqs,
                                                             EBookQuery **qs,
                                                             gboolean unref);

Creates a new EBookQuery which is the logical OR of the queries in qs.

`nqs` : | the number of queries to OR
`qs` : | pointer to an array of EBookQuery items
`unref` : | if TRUE, the new query takes ownership of the existing queries
Returns : | A new EBookQuery

### e_book_query_orv ()

    EBookQuery*         e_book_query_orv                    (EBookQuery *q,
                                                             ...);

Creates a new EBookQuery which is the logical OR of the queries specified.

`q` : | first EBookQuery
`...` : | NULL terminated list of EBookQuery pointers
Returns : | A new EBookQuery

### e_book_query_not ()

    EBookQuery*         e_book_query_not                    (EBookQuery *q,
                                                             gboolean unref);

Creates a new EBookQuery which is the opposite of q.

`q` : | an EBookQuery
`unref` : | if TRUE, the new query takes ownership of the existing queries
Returns : | the new EBookQuery

### e_book_query_field_exists ()

    EBookQuery*         e_book_query_field_exists           (EContactField field);

Creates a new EBookQuery which tests if the field `field` exists.

`field` : | a EContactField
Returns : | the new EBookQuery

### e_book_query_vcard_field_exists ()

    EBookQuery*         e_book_query_vcard_field_exists     (const char *field);

Creates a new EBookQuery which tests if the field `field` exists. `field` should be a vCard field name, such as FN or X-MSN.

`field` : | a field name
Returns : | the new EBookQuery

### e_book_query_field_test ()

    EBookQuery*         e_book_query_field_test             (EContactField field,
                                                             EBookQueryTest test,
                                                             const char *value);

Creates a new EBookQuery which tests `field` for `value` using the test `test`.

`field` : | an EContactField to test
`test` : | the test to apply
`value` : | the value to test for
Returns : | the new EBookQuery

### e_book_query_vcard_field_test ()

    EBookQuery*         e_book_query_vcard_field_test       (const char *field,
                                                             EBookQueryTest test,
                                                             const char *value);

Creates a new EBookQuery which tests `field` for `value` using the test `test`.

`field` : | a EVCard field name to test
`test` : | the test to apply
`value` : | the value to test for
Returns : | the new EBookQuery

### e_book_query_any_field_contains ()

    EBookQuery*         e_book_query_any_field_contains     (const char *value);

Creates a new EBookQuery which tests if any field contains `value`.

`value` : | a value
Returns : | the new EBookQuery

### e_book_query_copy ()

    EBookQuery*         e_book_query_copy                   (EBookQuery *q);

`q` : |
Returns : |