e-book-query

e-book-query — Querying and filtering contacts in an addressbook

Types and Values

Object Hierarchy

    GBoxed
    ╰── 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.