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       (GDataAuthorizer *authorizer);
    GDataAuthorizationDomain * gdata_contacts_service_get_primary_authorization_domain
                                                            (void);
    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,
                                                             GDestroyNotify destroy_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,
                                                             GDestroyNotify destroy_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 20. 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 21. 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       (GDataAuthorizer *authorizer);

Creates a new GDataContactsService using the given GDataAuthorizer. If `authorizer` is `NULL`, all requests are made as an unauthenticated user.

`authorizer` : | a GDataAuthorizer to authorize the service's requests, or `NULL`. [allow-none]
Returns : | a new GDataContactsService, or `NULL`; unref with `g_object_unref()`

Since 0.9.0

### gdata_contacts_service_get_primary_authorization_domain ()

    GDataAuthorizationDomain * gdata_contacts_service_get_primary_authorization_domain
                                                            (void);

The primary GDataAuthorizationDomain for interacting with Google Contacts. This will not normally need to be used, as it's used internally by the GDataContactsService methods. However, if using the plain GDataService methods to implement custom queries or requests which libgdata does not support natively, then this domain may be needed to authorize the requests.

The domain never changes, and is interned so that pointer comparison can be used to differentiate it from other authorization domains.

Returns : | the service's authorization domain. [transfer none]

Since 0.9.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`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [allow-none][scope call][closure progress_user_data]
`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,
                                                             GDestroyNotify destroy_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`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [allow-none][closure progress_user_data]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`destroy_progress_user_data` : | the function to call when `progress_callback` will not be called any more, or `NULL`. This function will be called with `progress_user_data` as a parameter and can be used to free any memory allocated for it. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.9.1

### 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`. [allow-none]
`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`. [allow-none]
`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`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [allow-none][scope call][closure progress_user_data]
`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,
                                                             GDestroyNotify destroy_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`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [allow-none][closure progress_user_data]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`destroy_progress_user_data` : | the function to call when `progress_callback` will not be called any more, or `NULL`. This function will be called with `progress_user_data` as a parameter and can be used to free any memory allocated for it. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.9.1

### 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`. [allow-none]
`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`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when insertion is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.7.0