GNOME.org

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.
Generated by GTK-Doc V1.19