← Back to branch summary

~ubuntu-branches/ubuntu/natty/libgdata/natty-updates

« back to all changes in this revision

Viewing changes to gdata/services/contacts/gdata-contacts-service.c

  • Committer: Bazaar Package Importer
  • Author(s): Robert Ancell
  • Date: 2011-01-05 11:09:00 UTC
  • mfrom: (1.1.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20110105110900-gkjnbslnr18s45us
Tags: 0.8.0-0ubuntu1
* New upstream release
* debian/control:
  - Use gir1.2 packages
  - Use standards version 3.9.1
  - Add Vcs-Bzr link
  - Rename libgdata10 to libgdata11
* debian/rules:
  - Drop simple-patchsys.mk
* debian/source:
  - Use source version 3.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
gdata/services/contacts/gdata-contacts-service.c
29
29
 * For more details of Google Contacts' GData API, see the <ulink type="http" url="http://code.google.com/apis/contacts/docs/2.0/reference.html">
30
30
 * online documentation</ulink>.
31
31
 *
 
32
 * <example>
 
33
 *      <title>Querying for Groups</title>
 
34
 *      <programlisting>
 
35
 *      GDataContactsService *service;
 
36
 *      GDataFeed *feed;
 
37
 *      GList *i;
 
38
 *      GError *error = NULL;
 
39
 *
 
40
 *      /<!-- -->* Create a service *<!-- -->/
 
41
 *      service = create_contacts_service ();
 
42
 *
 
43
 *      /<!-- -->* Query for groups *<!-- -->/
 
44
 *      feed = gdata_contacts_service_query_groups (service, NULL, NULL, NULL, NULL, &error);
 
45
 *
 
46
 *      g_object_unref (service);
 
47
 *
 
48
 *      if (error != NULL) {
 
49
 *              g_error ("Error querying for groups: %s", error->message);
 
50
 *              g_error_free (error);
 
51
 *              return;
 
52
 *      }
 
53
 *
 
54
 *      /<!-- -->* Iterate through the returned groups and do something with them *<!-- -->/
 
55
 *      for (i = gdata_feed_get_entries (feed); i != NULL; i = i->next) {
 
56
 *              const gchar *system_group_id, *group_name;
 
57
 *              gboolean is_system_group;
 
58
 *              GDataContactsGroup *group = GDATA_CONTACTS_GROUP (i->data);
 
59
 *
 
60
 *              /<!-- -->* Determine whether the group's a system group. If so, you should use the system group ID to provide your application's own
 
61
 *               * translations of the group name, as it's not translated. *<!-- -->/
 
62
 *              system_group_id = gdata_contacts_group_get_system_group_id (group);
 
63
 *              is_system_group = (system_group_id != NULL) ? TRUE : FALSE;
 
64
 *              group_name = (is_system_group == TRUE) ? get_group_name_for_system_group_id (system_group_id)
 
65
 *                                                     : gdata_entry_get_title (GDATA_ENTRY (group));
 
66
 *
 
67
 *              /<!-- -->* Do something with the group here, such as insert it into a UI. Note that system groups are not allowed to be deleted,
 
68
 *               * so you may want to make certain parts of your UI insensitive accordingly if the group is a system group. *<!-- -->/
 
69
 *      }
 
70
 *
 
71
 *      g_object_unref (feed);
 
72
 *      </programlisting>
 
73
 * </example>
 
74
 *
 
75
 * The Contacts service can be manipulated using batch operations, too. See the
 
76
 * <ulink type="http" url="http://code.google.com/apis/contacts/docs/3.0/developers_guide_protocol.html#Batch">online documentation on batch
 
77
 * operations</ulink> for more information.
 
78
 *
 
79
 * <example>
 
80
 *      <title>Performing a Batch Operation on Contacts</title>
 
81
 *      <programlisting>
 
82
 *      GDataContactsService *service;
 
83
 *      GDataBatchOperation *operation;
 
84
 *      GDataFeed *feed;
 
85
 *      GDataLink *batch_link;
 
86
 *      GList *i;
 
87
 *      GError *error = NULL;
 
88
 *
 
89
 *      /<!-- -->* Create a service *<!-- -->/
 
90
 *      service = create_contacts_service ();
 
91
 *
 
92
 *      /<!-- -->* Create the batch operation; this requires that we have done a query first so that we can get the batch link *<!-- -->/
 
93
 *      feed = do_some_query (service);
 
94
 *      batch_link = gdata_feed_look_up_link (feed, GDATA_LINK_BATCH);
 
95
 *      operation = gdata_batchable_create_operation (GDATA_BATCHABLE (service), gdata_link_get_uri (batch_link));
 
96
 *      g_object_unref (feed);
 
97
 *
 
98
 *      gdata_batch_operation_add_query (operation, contact_entry_id_to_query, GDATA_TYPE_CONTACTS_CONTACT,
 
99
 *                                       (GDataBatchOperationCallback) batch_query_cb, user_data);
 
100
 *      gdata_batch_operation_add_insertion (operation, new_entry, (GDataBatchOperationCallback) batch_insertion_cb, user_data);
 
101
 *      gdata_batch_operation_add_update (operation, old_entry, (GDataBatchOperationCallback) batch_update_cb, user_data);
 
102
 *      gdata_batch_operation_add_deletion (operation, entry_to_delete, (GDataBatchOperationCallback) batch_deletion_cb, user_data);
 
103
 *
 
104
 *      /<!-- -->* Run the batch operation and handle the results in the various callbacks *<!-- -->/
 
105
 *      gdata_test_batch_operation_run (operation, NULL, &error);
 
106
 *
 
107
 *      g_object_unref (operation);
 
108
 *      g_object_unref (service);
 
109
 *
 
110
 *      if (error != NULL) {
 
111
 *              g_error ("Error running batch operation: %s", error->message);
 
112
 *              g_error_free (error);
 
113
 *              return;
 
114
 *      }
 
115
 *
 
116
 *      static void
 
117
 *      batch_query_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
118
 *      {
 
119
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_QUERY *<!-- -->/
 
120
 *              /<!-- -->* Reference and do something with the returned entry. *<!-- -->/
 
121
 *      }
 
122
 *
 
123
 *      static void
 
124
 *      batch_insertion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
125
 *      {
 
126
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_INSERTION *<!-- -->/
 
127
 *              /<!-- -->* Reference and do something with the returned entry. *<!-- -->/
 
128
 *      }
 
129
 *
 
130
 *      static void
 
131
 *      batch_update_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
132
 *      {
 
133
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_UPDATE *<!-- -->/
 
134
 *              /<!-- -->* Reference and do something with the returned entry. *<!-- -->/
 
135
 *      }
 
136
 *
 
137
 *      static void
 
138
 *      batch_deletion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
139
 *      {
 
140
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_DELETION, entry == NULL *<!-- -->/
 
141
 *      }
 
142
 *      </programlisting>
 
143
 * </example>
 
144
 *
32
145
 * Since: 0.2.0
33
146
 **/
34
147