GDataContactsService

## GDataContactsService GDataContactsService — GData Contacts service object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataContactsService;
                        GDataContactsServiceClass;
    GDataContactsService * gdata_contacts_service_new       (const gchar *client_id);
    GDataFeed *         gdata_contacts_service_query_contacts
                                                            (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_contacts_service_query_contacts_async
                                                            (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataContactsContact * gdata_contacts_service_insert_contact
                                                            (GDataContactsService *self,
                                                             GDataContactsContact *contact,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_contacts_service_insert_contact_async
                                                            (GDataContactsService *self,
                                                             GDataContactsContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataFeed *         gdata_contacts_service_query_groups (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_contacts_service_query_groups_async
                                                            (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataContactsGroup * gdata_contacts_service_insert_group
                                                            (GDataContactsService *self,
                                                             GDataContactsGroup *group,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_contacts_service_insert_group_async
                                                            (GDataContactsService *self,
                                                             GDataContactsGroup *group,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----GDataService
             +----GDataContactsService

## Implemented Interfaces

GDataContactsService implements GDataBatchable.

## Description

GDataContactsService is a subclass of GDataService for communicating with the GData API of Google Contacts. It supports querying for, inserting, editing and deleting contacts from a Google address book.

For more details of Google Contacts' GData API, see the online documentation.

Example 14. Querying for Groups

    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
    GDataContactsService *service;
    GDataFeed *feed;
    GList *i;
    GError *error = NULL;

    /* Create a service */
    service = create_contacts_service ();

    /* Query for groups */
    feed = gdata_contacts_service_query_groups (service, NULL, NULL, NULL, NULL, &error);

    g_object_unref (service);

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

    /* Iterate through the returned groups and do something with them */
    for (i = gdata_feed_get_entries (feed); i != NULL; i = i->next) {
        const gchar *system_group_id, *group_name;
        gboolean is_system_group;
        GDataContactsGroup *group = GDATA_CONTACTS_GROUP (i->data);

        /* Determine whether the group's a system group. If so, you should use the system group ID to provide your application's own
         * translations of the group name, as it's not translated. */
        system_group_id = gdata_contacts_group_get_system_group_id (group);
        is_system_group = (system_group_id != NULL) ? TRUE : FALSE;
        group_name = (is_system_group == TRUE) ? get_group_name_for_system_group_id (system_group_id)
                                               : gdata_entry_get_title (GDATA_ENTRY (group));

        /* Do something with the group here, such as insert it into a UI. Note that system groups are not allowed to be deleted,
         * so you may want to make certain parts of your UI insensitive accordingly if the group is a system group. */
    }

    g_object_unref (feed);

The Contacts service can be manipulated using batch operations, too. See the online documentation on batch operations for more information.

Example 15. Performing a Batch Operation on 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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    GDataContactsService *service;
    GDataBatchOperation *operation;
    GDataFeed *feed;
    GDataLink *batch_link;
    GList *i;
    GError *error = NULL;

    /* Create a service */
    service = create_contacts_service ();

    /* Create the batch operation; this requires that we have done a query first so that we can get the batch link */
    feed = do_some_query (service);
    batch_link = gdata_feed_look_up_link (feed, GDATA_LINK_BATCH);
    operation = gdata_batchable_create_operation (GDATA_BATCHABLE (service), gdata_link_get_uri (batch_link));
    g_object_unref (feed);

    gdata_batch_operation_add_query (operation, contact_entry_id_to_query, GDATA_TYPE_CONTACTS_CONTACT,
                                     (GDataBatchOperationCallback) batch_query_cb, user_data);
    gdata_batch_operation_add_insertion (operation, new_entry, (GDataBatchOperationCallback) batch_insertion_cb, user_data);
    gdata_batch_operation_add_update (operation, old_entry, (GDataBatchOperationCallback) batch_update_cb, user_data);
    gdata_batch_operation_add_deletion (operation, entry_to_delete, (GDataBatchOperationCallback) batch_deletion_cb, user_data);

    /* Run the batch operation and handle the results in the various callbacks */
    gdata_test_batch_operation_run (operation, NULL, &error);

    g_object_unref (operation);
    g_object_unref (service);

    if (error != NULL) {
        g_error ("Error running batch operation: %s", error->message);
        g_error_free (error);
        return;
    }

    static void
    batch_query_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
        /* operation_type == GDATA_BATCH_OPERATION_QUERY */
        /* Reference and do something with the returned entry. */
    }

    static void
    batch_insertion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
        /* operation_type == GDATA_BATCH_OPERATION_INSERTION */
        /* Reference and do something with the returned entry. */
    }

    static void
    batch_update_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
        /* operation_type == GDATA_BATCH_OPERATION_UPDATE */
        /* Reference and do something with the returned entry. */
    }

    static void
    batch_deletion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
        /* operation_type == GDATA_BATCH_OPERATION_DELETION, entry == NULL */
    }

## Details

### GDataContactsService

    typedef struct _GDataContactsService GDataContactsService;

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

Since 0.2.0

### GDataContactsServiceClass

    typedef struct {
    } GDataContactsServiceClass;

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

Since 0.2.0

### gdata_contacts_service_new ()

    GDataContactsService * gdata_contacts_service_new       (const gchar *client_id);

Creates a new GDataContactsService. The `client_id` must be unique for your application, and as registered with Google.

`client_id` : | your application's client ID
Returns : | a new GDataContactsService, or `NULL`

Since 0.2.0

### gdata_contacts_service_query_contacts ()

    GDataFeed *         gdata_contacts_service_query_contacts
                                                            (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);

Queries the service to return a list of contacts matching the given `query`.

For more details, see `gdata_service_query()`.

`self` : | a GDataContactsService
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [scope call]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`error` : | a GError, or `NULL`
Returns : | a GDataFeed of query results; unref with `g_object_unref()`. [transfer full]

Since 0.2.0

### gdata_contacts_service_query_contacts_async ()

    void                gdata_contacts_service_query_contacts_async
                                                            (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Queries the service to return a list of contacts matching the given `query`. `self` and `query` are all reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see `gdata_contacts_service_query_contacts()`, which is the synchronous version of this function, and `gdata_service_query_async()`, which is the base asynchronous query function.

`self` : | a GDataContactsService
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.2.0

### gdata_contacts_service_insert_contact ()

    GDataContactsContact * gdata_contacts_service_insert_contact
                                                            (GDataContactsService *self,
                                                             GDataContactsContact *contact,
                                                             GCancellable *cancellable,
                                                             GError **error);

Inserts `contact` by uploading it to the online contacts service.

For more details, see `gdata_service_insert_entry()`.

`self` : | a GDataContactsService
`contact` : | the GDataContactsContact to insert
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataContactsContact, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.2.0

### gdata_contacts_service_insert_contact_async ()

    void                gdata_contacts_service_insert_contact_async
                                                            (GDataContactsService *self,
                                                             GDataContactsContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Inserts `contact` by uploading it to the online contacts service. `self` and `contact` are both reffed when this function is called, so can safely be unreffed after this function returns.

`callback` should call `gdata_service_insert_entry_finish()` to obtain a GDataContactsContact representing the inserted contact and to check for possible errors.

For more details, see `gdata_contacts_service_insert_contact()`, which is the synchronous version of this function, and `gdata_service_insert_entry_async()`, which is the base asynchronous insertion function.

`self` : | a GDataContactsService
`contact` : | the GDataContactsContact to insert
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when insertion is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.7.0

### gdata_contacts_service_query_groups ()

    GDataFeed *         gdata_contacts_service_query_groups (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);

Queries the service to return a list of groups matching the given `query`.

For more details, see `gdata_service_query()`.

`self` : | a GDataContactsService
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [scope call]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`error` : | a GError, or `NULL`
Returns : | a GDataFeed of query results; unref with `g_object_unref()`. [transfer full]

Since 0.7.0

### gdata_contacts_service_query_groups_async ()

    void                gdata_contacts_service_query_groups_async
                                                            (GDataContactsService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Queries the service to return a list of groups matching the given `query`. `self` and `query` are all reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see `gdata_contacts_service_query_groups()`, which is the synchronous version of this function, and `gdata_service_query_async()`, which is the base asynchronous query function.

`self` : | a GDataContactsService
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.7.0

### gdata_contacts_service_insert_group ()

    GDataContactsGroup * gdata_contacts_service_insert_group
                                                            (GDataContactsService *self,
                                                             GDataContactsGroup *group,
                                                             GCancellable *cancellable,
                                                             GError **error);

Inserts a new contact group described by `group`. The user must be authenticated to use this function.

`self` : | a GDataContactsService
`group` : | a GDataContactsGroup to create on the server
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | the inserted GDataContactsGroup; unref with `g_object_unref()`. [transfer full]

Since 0.7.0

### gdata_contacts_service_insert_group_async ()

    void                gdata_contacts_service_insert_group_async
                                                            (GDataContactsService *self,
                                                             GDataContactsGroup *group,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Inserts a new contact group described by `group`. The user must be authenticated to use this function. `self` and `group` are both reffed when this function is called, so can safely be unreffed after this function returns.

`callback` should call `gdata_service_insert_entry_finish()` to obtain a GDataContactsGroup representing the inserted group and to check for possible errors.

For more details, see `gdata_contacts_service_insert_group()`, which is the synchronous version of this function, and `gdata_service_insert_entry_async()`, which is the base asynchronous insertion function.

`self` : | a GDataContactsService
`group` : | the GDataContactsGroup to insert
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when insertion is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.7.0