## EBookQuery

EBookQuery — Querying and filtering contacts in an addressbook

## Synopsis

    #include <libebook-contacts/libebook-contacts.h>

    enum                EBookQueryTest;
                        EBookQuery;
    EBookQuery *        e_book_query_from_string            (const gchar *query_string);
    gchar *             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                    (gint nqs,
                                                             EBookQuery **qs,
                                                             gboolean unref);
    EBookQuery *        e_book_query_andv                   (EBookQuery *q,
                                                             ...);
    EBookQuery *        e_book_query_or                     (gint 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 gchar *field);
    EBookQuery *        e_book_query_field_test             (EContactField field,
                                                             EBookQueryTest test,
                                                             const gchar *value);
    EBookQuery *        e_book_query_vcard_field_test       (const gchar *field,
                                                             EBookQueryTest test,
                                                             const gchar *value);
    EBookQuery *        e_book_query_any_field_contains     (const gchar *value);
    EBookQuery *        e_book_query_copy                   (EBookQuery *q);

## Description

This utility can be used to conveniently create search expressions which can later be used to query and filter results in the EBookClient, EBookClientView and EBookClientCursor interfaces.

## Details

### enum EBookQueryTest

    typedef enum {
      E_BOOK_QUERY_IS = 0,
      E_BOOK_QUERY_CONTAINS,
      E_BOOK_QUERY_BEGINS_WITH,
      E_BOOK_QUERY_ENDS_WITH,

      E_BOOK_QUERY_EQUALS_PHONE_NUMBER,
      E_BOOK_QUERY_EQUALS_NATIONAL_PHONE_NUMBER,
      E_BOOK_QUERY_EQUALS_SHORT_PHONE_NUMBER,

      E_BOOK_QUERY_REGEX_NORMAL,
      E_BOOK_QUERY_REGEX_RAW,

      /*
        Consider these "coming soon".

        E_BOOK_QUERY_LT,
        E_BOOK_QUERY_LE,
        E_BOOK_QUERY_GT,
        E_BOOK_QUERY_GE,
        E_BOOK_QUERY_EQ,
      */

      E_BOOK_QUERY_LAST
    } EBookQueryTest;

The kind of test a query created by `e_book_query_field_test()` shall perform.

See also: `e_phone_number_compare_strings()`.

`E_BOOK_QUERY_IS` | look for exact match of the supplied test value
`E_BOOK_QUERY_CONTAINS` | check if a field contains the test value
`E_BOOK_QUERY_BEGINS_WITH` | check if a field starts with the test value
`E_BOOK_QUERY_ENDS_WITH` | check if a field ends with the test value
`E_BOOK_QUERY_EQUALS_PHONE_NUMBER` | check if a field matches with a value tested using `e_phone_number_compare_strings()`, the match must be of strenth `E_PHONE_NUMBER_MATCH_EXACT` for this query to return any matches.
`E_BOOK_QUERY_EQUALS_NATIONAL_PHONE_NUMBER` | check if a field matches with a value tested using `e_phone_number_compare_strings()`, the match must be at least of strength `E_PHONE_NUMBER_MATCH_NATIONAL` for this query to return any matches.
`E_BOOK_QUERY_EQUALS_SHORT_PHONE_NUMBER` | check if a field matches with a value tested using `e_phone_number_compare_strings()`, the match must be at least of strength `E_PHONE_NUMBER_MATCH_SHORT` for this query to return any matches.
`E_BOOK_QUERY_REGEX_NORMAL` | A regular expression query against contact data normalized with `e_util_utf8_normalize()`, the normalized data is lower case with any accents removed.
`E_BOOK_QUERY_REGEX_RAW` | A regular expression query against raw contact data, this is usually slower than a `E_BOOK_QUERY_REGEX_NORMAL` as it implies that EVCards must be parsed in order to get the raw data for comparison.
`E_BOOK_QUERY_LAST` | End marker for the EBookQueryTest enumeration, not a valid query test.

### EBookQuery

    typedef struct _EBookQuery EBookQuery;

### e_book_query_from_string ()

    EBookQuery *        e_book_query_from_string            (const gchar *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 ()

    gchar *             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                    (gint 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                     (gint 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 gchar *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 gchar *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 gchar *field,
                                                             EBookQueryTest test,
                                                             const gchar *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

Since 2.22

### e_book_query_any_field_contains ()

    EBookQuery *        e_book_query_any_field_contains     (const gchar *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);

Creates a copy of `q`.

`q` : | an EBookQuery
Returns : | A new EBookQuery identical to `q`.