## EBookQuery

EBookQuery — Querying and filtering contacts in an addressbook

## Functions

EBookQuery * | e_book_query_from_string ()
gchar * | e_book_query_to_string ()
EBookQuery * | e_book_query_ref ()
void | e_book_query_unref ()
EBookQuery * | e_book_query_and ()
EBookQuery * | e_book_query_andv ()
EBookQuery * | e_book_query_or ()
EBookQuery * | e_book_query_orv ()
EBookQuery * | e_book_query_not ()
EBookQuery * | e_book_query_field_exists ()
EBookQuery * | e_book_query_vcard_field_exists ()
EBookQuery * | e_book_query_field_test ()
EBookQuery * | e_book_query_vcard_field_test ()
EBookQuery * | e_book_query_any_field_contains ()
EBookQuery * | e_book_query_copy ()

## Types and Values

enum | EBookQueryTest
| EBookQuery

## Includes

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

## 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.

## Functions

### 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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

value | a value |

#### Returns

the new EBookQuery

### e_book_query_copy ()

    EBookQuery *
    e_book_query_copy (EBookQuery *q);

Creates a copy of `q` .

#### Parameters

q | an EBookQuery |

#### Returns

A new EBookQuery identical to `q` .

## Types and Values

### enum EBookQueryTest

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

See also: `e_phone_number_compare_strings()`.

#### Members

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;