e-book-query
3
LIBEBOOK Library

# 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_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_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 :