GData Reference Manual: GDataContactsQuery

## GDataContactsQuery GDataContactsQuery — GData Contacts query object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <gdata/services/contacts/gdata-contacts-query.h>

                        GDataContactsQuery;
                        GDataContactsQueryClass;
    GDataContactsQuery * gdata_contacts_query_new           (const gchar *q);
    GDataContactsQuery * gdata_contacts_query_new_with_limits
                                                            (const gchar *q,
                                                             guint start_index,
                                                             guint max_results);
    const gchar *       gdata_contacts_query_get_order_by   (GDataContactsQuery *self);
    void                gdata_contacts_query_set_order_by   (GDataContactsQuery *self,
                                                             const gchar *order_by);
    const gchar *       gdata_contacts_query_get_sort_order (GDataContactsQuery *self);
    void                gdata_contacts_query_set_sort_order (GDataContactsQuery *self,
                                                             const gchar *sort_order);
    gboolean            gdata_contacts_query_show_deleted   (GDataContactsQuery *self);
    void                gdata_contacts_query_set_show_deleted
                                                            (GDataContactsQuery *self,
                                                             gboolean show_deleted);
    const gchar *       gdata_contacts_query_get_group      (GDataContactsQuery *self);
    void                gdata_contacts_query_set_group      (GDataContactsQuery *self,
                                                             const gchar *group);

## Object Hierarchy

      GObject
       +----GDataQuery
             +----GDataContactsQuery

## Properties

      "group"                    gchar*                : Read / Write
      "order-by"                 gchar*                : Read / Write
      "show-deleted"             gboolean              : Read / Write
      "sort-order"               gchar*                : Read / Write

## Description

GDataContactsQuery represents a collection of query parameters specific to the Google Contacts service, which go above and beyond those catered for by GDataQuery.

For more information on the custom GData query parameters supported by GDataContactsQuery, see the online documentation.

Example 22. Querying for Contacts

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    GDataContactsService *service;
    gchar *group_id;
    GDataContactsQuery *query;
    GDataFeed *feed;
    GList *i;
    GError *error = NULL;

    /* Create a service and return the group we're querying within. */
    service = create_contacts_service ();
    group_id = query_user_for_group (service);

    /* Create the query to use. We're going to query for contacts which match the search term "John" within a given group,
     * including deleted contacts. The group is specified by its ID. */
    query = gdata_contacts_query_new ("John");
    gdata_contacts_query_set_show_deleted (query, TRUE);
    gdata_contacts_query_set_group (query, group_id);

    g_free (group_id);

    /* Execute the query */
    feed = gdata_contacts_service_query_contacts (service, query, NULL, NULL, NULL, &error);

    g_object_unref (query);
    g_object_unref (service);

    if (error != NULL) {
        g_error ("Error querying for contacts: %s", error->message);
        g_error_free (error);
        return;
    }

    /* Iterate through the returned contacts and do something with them */
    for (i = gdata_feed_get_entries (feed); i != NULL; i = i->next) {
        GDataContactsContact *contact = GDATA_CONTACTS_CONTACT (i->data);

        /* Do something with the contact here, such as insert it into a UI */
    }

    g_object_unref (feed);

## Details

### GDataContactsQuery

    typedef struct _GDataContactsQuery GDataContactsQuery;

All the fields in the GDataContactsQuery structure are private and should never be accessed directly.

Since 0.2.0

### GDataContactsQueryClass

    typedef struct {
    } GDataContactsQueryClass;

All the fields in the GDataContactsQueryClass structure are private and should never be accessed directly.

Since 0.2.0

### gdata_contacts_query_new ()

    GDataContactsQuery * gdata_contacts_query_new           (const gchar *q);

Creates a new GDataContactsQuery with its "q" property set to `q`.

`q` : | a query string, or `NULL`. [allow-none]
Returns : | a new GDataContactsQuery

Since 0.2.0

### gdata_contacts_query_new_with_limits ()

    GDataContactsQuery * gdata_contacts_query_new_with_limits
                                                            (const gchar *q,
                                                             guint start_index,
                                                             guint max_results);

Creates a new GDataContactsQuery with its "q" property set to `q`, and the limits `start_index` and `max_results` applied.

`q` : | a query string, or `NULL`. [allow-none]
`start_index` : | a one-based start index for the results, or `0`
`max_results` : | the maximum number of results to return, or `0`
Returns : | a new GDataContactsQuery

Since 0.2.0

### gdata_contacts_query_get_order_by ()

    const gchar *       gdata_contacts_query_get_order_by   (GDataContactsQuery *self);

Gets the "order-by" property.

`self` : | a GDataContactsQuery
Returns : | the order by property, or `NULL` if it is unset

Since 0.2.0

### gdata_contacts_query_set_order_by ()

    void                gdata_contacts_query_set_order_by   (GDataContactsQuery *self,
                                                             const gchar *order_by);

Sets the "order-by" property of the GDataContactsQuery to the new order by string, `order_by`.

Set `order_by` to `NULL` to unset the property in the query URI.

`self` : | a GDataContactsQuery
`order_by` : | a new order by string, or `NULL`. [allow-none]

Since 0.2.0

### gdata_contacts_query_get_sort_order ()

    const gchar *       gdata_contacts_query_get_sort_order (GDataContactsQuery *self);

Gets the "sort-order" property.

`self` : | a GDataContactsQuery
Returns : | the sort order property, or `NULL` if it is unset

Since 0.2.0

### gdata_contacts_query_set_sort_order ()

    void                gdata_contacts_query_set_sort_order (GDataContactsQuery *self,
                                                             const gchar *sort_order);

Sets the "sort-order" property of the GDataContactsQuery to the new sort order string, `sort_order`.

Set `sort_order` to `NULL` to unset the property in the query URI.

`self` : | a GDataContactsQuery
`sort_order` : | a new sort order string, or `NULL`. [allow-none]

Since 0.2.0

### gdata_contacts_query_show_deleted ()

    gboolean            gdata_contacts_query_show_deleted   (GDataContactsQuery *self);

Gets the "show-deleted" property.

`self` : | a GDataContactsQuery
Returns : | `TRUE` if deleted contacts should be shown, `FALSE` otherwise

Since 0.2.0

### gdata_contacts_query_set_show_deleted ()

    void                gdata_contacts_query_set_show_deleted
                                                            (GDataContactsQuery *self,
                                                             gboolean show_deleted);

Sets the "show-deleted" property of the GDataContactsQuery.

`self` : | a GDataContactsQuery
`show_deleted` : | `TRUE` to show deleted contacts, `FALSE` otherwise

Since 0.2.0

### gdata_contacts_query_get_group ()

    const gchar *       gdata_contacts_query_get_group      (GDataContactsQuery *self);

Gets the "group" property.

`self` : | a GDataContactsQuery
Returns : | the group property, or `NULL` if it is unset

Since 0.2.0

### gdata_contacts_query_set_group ()

    void                gdata_contacts_query_set_group      (GDataContactsQuery *self,
                                                             const gchar *group);

Sets the "group" property of the GDataContactsQuery to the new group ID URI, `group`.

Set `group` to `NULL` to unset the property in the query URI.

`self` : | a GDataContactsQuery
`group` : | a new group ID URI, or `NULL`. [allow-none]

Since 0.2.0

## Property Details

### The `"group"` property

      "group"                    gchar*                : Read / Write

Constrains the results to only those belonging to the group specified. The value of this parameter should be a group ID URI.

Default value: NULL

Since 0.2.0

### The `"order-by"` property

      "order-by"                 gchar*                : Read / Write

Sorting criterion. The only supported value is `lastmodified`.

Default value: NULL

Since 0.2.0

### The `"show-deleted"` property

      "show-deleted"             gboolean              : Read / Write

Whether to include deleted contacts in the query feed. Deleted contacts return `TRUE` from `gdata_contacts_contact_is_deleted()`, and have no other information. They do not normally appear in query results.

Default value: FALSE

Since 0.2.0

### The `"sort-order"` property

      "sort-order"               gchar*                : Read / Write

Sorting order direction. Can be either `ascending` or `descending`.

Default value: NULL

Since 0.2.0