|  |  |  | Evolution-Data-Server Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | ||||
#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);
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.
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().
| look for exact match of the supplied test value | |
| check if a field contains the test value | |
| check if a field starts with the test value | |
| check if a field ends with the test value | |
| check if a field matches with a value tested
using e_phone_number_compare_strings(), the match must be of strenthE_PHONE_NUMBER_MATCH_EXACTfor this query to return any matches. | |
| check if a field matches with a value tested
using e_phone_number_compare_strings(), the match must be at least of strengthE_PHONE_NUMBER_MATCH_NATIONALfor this query to return any matches. | |
| check if a field matches with a value tested
using e_phone_number_compare_strings(), the match must be at least of strengthE_PHONE_NUMBER_MATCH_SHORTfor this query to return any matches. | |
| A regular expression query against contact data normalized with e_util_utf8_normalize(),
the normalized data is lower case with any accents removed. | |
| A regular expression query against raw contact data, this is usually slower than
a E_BOOK_QUERY_REGEX_NORMALas it implies that EVCards must be parsed in order to get the raw data
for comparison. | |
| End marker for the EBookQueryTest enumeration, not a valid query test. | 
EBookQuery *        e_book_query_from_string            (const gchar *query_string);
Parse query_string and return a new EBookQuery representing it.
| 
 | the query | 
| Returns : | the new EBookQuery. | 
gchar *             e_book_query_to_string              (EBookQuery *q);
Return the string representation of q.
| 
 | an EBookQuery | 
| Returns : | The string form of the query. This string should be freed when finished with. | 
EBookQuery *        e_book_query_ref                    (EBookQuery *q);
Increment the reference count on q.
| 
 | a EBookQuery | 
| Returns : | q | 
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.
| 
 | an EBookQuery | 
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.
| 
 | the number of queries to AND | 
| 
 | pointer to an array of EBookQuery items | 
| 
 | if TRUE, the new query takes ownership of the existing queries | 
| Returns : | A new EBookQuery | 
EBookQuery * e_book_query_andv (EBookQuery *q,...);
Creates a new EBookQuery which is the logical AND of the queries specified.
| 
 | first EBookQuery | 
| 
 | NULLterminated list of EBookQuery pointers | 
| Returns : | A new EBookQuery | 
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.
| 
 | the number of queries to OR | 
| 
 | pointer to an array of EBookQuery items | 
| 
 | if TRUE, the new query takes ownership of the existing queries | 
| Returns : | A new EBookQuery | 
EBookQuery * e_book_query_orv (EBookQuery *q,...);
Creates a new EBookQuery which is the logical OR of the queries specified.
| 
 | first EBookQuery | 
| 
 | NULLterminated list of EBookQuery pointers | 
| Returns : | A new EBookQuery | 
EBookQuery * e_book_query_not (EBookQuery *q,gboolean unref);
Creates a new EBookQuery which is the opposite of #q.
| 
 | an EBookQuery | 
| 
 | if TRUE, the new query takes ownership of the existing queries | 
| Returns : | the new EBookQuery | 
EBookQuery *        e_book_query_field_exists           (EContactField field);
Creates a new EBookQuery which tests if the field field exists.
| 
 | a EContactField | 
| Returns : | the new EBookQuery | 
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.
| 
 | a field name | 
| Returns : | the new EBookQuery | 
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.
| 
 | an EContactField to test | 
| 
 | the test to apply | 
| 
 | the value to test for | 
| Returns : | the new EBookQuery | 
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.
| 
 | a EVCard field name to test | 
| 
 | the test to apply | 
| 
 | the value to test for | 
| Returns : | the new EBookQuery | 
Since 2.22
EBookQuery *        e_book_query_any_field_contains     (const gchar *value);
Creates a new EBookQuery which tests if any field contains value.
| 
 | a value | 
| Returns : | the new EBookQuery | 
EBookQuery *        e_book_query_copy                   (EBookQuery *q);
Creates a copy of q.
| 
 | an EBookQuery | 
| Returns : | A new EBookQuery identical to q. |