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
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);
    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