← Back to branch summary

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

« back to all changes in this revision

Viewing changes to gdata/services/calendar/gdata-calendar-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/calendar/gdata-calendar-service.c
28
28
 *
29
29
 * For more details of Google Calendar's GData API, see the <ulink type="http" url="http://code.google.com/apis/calendar/docs/2.0/reference.html">
30
30
 * online documentation</ulink>.
 
31
 *
 
32
 * Each calendar accessible through the service has an access control list (ACL) which defines the level of access to the calendar to each user, and
 
33
 * which users the calendar is shared with. For more information about ACLs for calendars, see the
 
34
 * <ulink type="http" url="http://code.google.com/apis/calendar/data/2.0/developers_guide_protocol.html#SharingACalendar">online documentation on
 
35
 * sharing calendars</ulink>.
 
36
 *
 
37
 * <example>
 
38
 *      <title>Retrieving the Access Control List for a Calendar</title>
 
39
 *      <programlisting>
 
40
 *      GDataCalendarService *service;
 
41
 *      GDataCalendarCalendar *calendar;
 
42
 *      GDataFeed *acl_feed;
 
43
 *      GDataAccessRule *rule, *new_rule;
 
44
 *      GDataLink *acl_link;
 
45
 *      GList *i;
 
46
 *      GError *error = NULL;
 
47
 *
 
48
 *      /<!-- -->* Create a service and retrieve a calendar to work on *<!-- -->/
 
49
 *      service = create_calendar_service ();
 
50
 *      calendar = get_calendar (service);
 
51
 *
 
52
 *      /<!-- -->* Query the service for the ACL for the given calendar *<!-- -->/
 
53
 *      acl_feed = gdata_access_handler_get_rules (GDATA_ACCESS_HANDLER (calendar), GDATA_SERVICE (service), NULL, NULL, NULL, &error);
 
54
 *
 
55
 *      if (error != NULL) {
 
56
 *              g_error ("Error getting ACL feed for calendar: %s", error->message);
 
57
 *              g_error_free (error);
 
58
 *              g_object_unref (calendar);
 
59
 *              g_object_unref (service);
 
60
 *              return;
 
61
 *      }
 
62
 *
 
63
 *      /<!-- -->* Iterate through the ACL *<!-- -->/
 
64
 *      for (i = gdata_feed_get_entries (acl_feed); i != NULL; i = i->next) {
 
65
 *              const gchar *scope_value;
 
66
 *
 
67
 *              rule = GDATA_ACCESS_RULE (i->data);
 
68
 *
 
69
 *              /<!-- -->* Do something with the access rule here. As an example, we update the rule applying to test@gmail.com and delete all
 
70
 *               * the other rules. We then insert another rule for example@gmail.com below. *<!-- -->/
 
71
 *              gdata_access_rule_get_scope (rule, NULL, &scope_value);
 
72
 *              if (scope_value != NULL && strcmp (scope_value, "test@gmail.com") == 0) {
 
73
 *                      GDataAccessRule *updated_rule;
 
74
 *
 
75
 *                      /<!-- -->* Update the rule to make test@gmail.com an editor (full read/write access to the calendar, but they can't change
 
76
 *                       * the ACL). *<!-- -->/
 
77
 *                      gdata_access_rule_set_role (rule, GDATA_CALENDAR_ACCESS_ROLE_EDITOR);
 
78
 *                      updated_rule = GDATA_ACCESS_RULE (gdata_service_update_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error));
 
79
 *
 
80
 *                      if (error != NULL) {
 
81
 *                              g_error ("Error updating access rule for %s: %s", scope_value, error->message);
 
82
 *                              g_error_free (error);
 
83
 *                              g_object_unref (acl_feed);
 
84
 *                              g_object_unref (calendar);
 
85
 *                              g_object_unref (service);
 
86
 *                              return;
 
87
 *                      }
 
88
 *
 
89
 *                      g_object_unref (updated_rule);
 
90
 *              } else {
 
91
 *                      /<!-- -->* Delete any rule which doesn't apply to test@gmail.com *<!-- -->/
 
92
 *                      gdata_service_delete_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error);
 
93
 *
 
94
 *                      if (error != NULL) {
 
95
 *                              g_error ("Error deleting access rule for %s: %s", scope_value, error->message);
 
96
 *                              g_error_free (error);
 
97
 *                              g_object_unref (acl_feed);
 
98
 *                              g_object_unref (calendar);
 
99
 *                              g_object_unref (service);
 
100
 *                              return;
 
101
 *                      }
 
102
 *              }
 
103
 *      }
 
104
 *
 
105
 *      g_object_unref (acl_feed);
 
106
 *
 
107
 *      /<!-- -->* Create and insert a new access rule for example@gmail.com which allows them to view free/busy information for events in the
 
108
 *       * calendar, but doesn't allow them to view the full event details. *<!-- -->/
 
109
 *      rule = gdata_access_rule_new (NULL);
 
110
 *      gdata_access_rule_set_role (rule, GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY);
 
111
 *      gdata_access_rule_set_scope (rule, GDATA_ACCESS_SCOPE_USER, "example@gmail.com");
 
112
 *
 
113
 *      acl_link = gdata_entry_look_up_link (GDATA_ENTRY (calendar), GDATA_LINK_ACCESS_CONTROL_LIST);
 
114
 *      new_rule = GDATA_ACCESS_RULE (gdata_service_insert_entry (GDATA_SERVICE (service), gdata_link_get_uri (acl_link), GDATA_ENTRY (rule),
 
115
 *                                                                NULL, &error));
 
116
 *
 
117
 *      g_object_unref (rule);
 
118
 *      g_object_unref (calendar);
 
119
 *      g_object_unref (service);
 
120
 *
 
121
 *      if (error != NULL) {
 
122
 *              g_error ("Error inserting access rule: %s", error->message);
 
123
 *              g_error_free (error);
 
124
 *              return;
 
125
 *      }
 
126
 *
 
127
 *      g_object_unref (acl_link);
 
128
 *      </programlisting>
 
129
 * </example>
 
130
 *
 
131
 * The Calendar service can be manipulated using batch operations, too. See the
 
132
 * <ulink type="http" url="http://code.google.com/apis/calendar/data/2.0/developers_guide_protocol.html#Batch">online documentation on batch
 
133
 * operations</ulink> for more information.
 
134
 *
 
135
 * <example>
 
136
 *      <title>Performing a Batch Operation on a Calendar</title>
 
137
 *      <programlisting>
 
138
 *      GDataCalendarService *service;
 
139
 *      GDataCalendarCalendar *calendar;
 
140
 *      GDataBatchOperation *operation;
 
141
 *      GDataLink *batch_link;
 
142
 *      GList *i;
 
143
 *      GError *error = NULL;
 
144
 *
 
145
 *      /<!-- -->* Create a service and retrieve a calendar to work on *<!-- -->/
 
146
 *      service = create_calendar_service ();
 
147
 *      calendar = get_calendar (service);
 
148
 *
 
149
 *      /<!-- -->* Create the batch operation *<!-- -->/
 
150
 *      batch_link = gdata_entry_look_up_link (GDATA_ENTRY (calendar), GDATA_LINK_BATCH);
 
151
 *      operation = gdata_batchable_create_operation (GDATA_BATCHABLE (service), gdata_link_get_uri (batch_link));
 
152
 *
 
153
 *      g_object_unref (calendar);
 
154
 *
 
155
 *      gdata_batch_operation_add_query (operation, event_entry_id_to_query, GDATA_TYPE_CALENDAR_EVENT,
 
156
 *                                       (GDataBatchOperationCallback) batch_query_cb, user_data);
 
157
 *      gdata_batch_operation_add_insertion (operation, new_entry, (GDataBatchOperationCallback) batch_insertion_cb, user_data);
 
158
 *      gdata_batch_operation_add_update (operation, old_entry, (GDataBatchOperationCallback) batch_update_cb, user_data);
 
159
 *      gdata_batch_operation_add_deletion (operation, entry_to_delete, (GDataBatchOperationCallback) batch_deletion_cb, user_data);
 
160
 *
 
161
 *      /<!-- -->* Run the batch operation and handle the results in the various callbacks *<!-- -->/
 
162
 *      gdata_test_batch_operation_run (operation, NULL, &error);
 
163
 *
 
164
 *      g_object_unref (operation);
 
165
 *      g_object_unref (service);
 
166
 *
 
167
 *      if (error != NULL) {
 
168
 *              g_error ("Error running batch operation: %s", error->message);
 
169
 *              g_error_free (error);
 
170
 *              return;
 
171
 *      }
 
172
 *
 
173
 *      static void
 
174
 *      batch_query_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
175
 *      {
 
176
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_QUERY *<!-- -->/
 
177
 *              /<!-- -->* Reference and do something with the returned entry. *<!-- -->/
 
178
 *      }
 
179
 *
 
180
 *      static void
 
181
 *      batch_insertion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
182
 *      {
 
183
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_INSERTION *<!-- -->/
 
184
 *              /<!-- -->* Reference and do something with the returned entry. *<!-- -->/
 
185
 *      }
 
186
 *
 
187
 *      static void
 
188
 *      batch_update_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
189
 *      {
 
190
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_UPDATE *<!-- -->/
 
191
 *              /<!-- -->* Reference and do something with the returned entry. *<!-- -->/
 
192
 *      }
 
193
 *
 
194
 *      static void
 
195
 *      batch_deletion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
 
196
 *      {
 
197
 *              /<!-- -->* operation_type == GDATA_BATCH_OPERATION_DELETION, entry == NULL *<!-- -->/
 
198
 *      }
 
199
 *      </programlisting>
 
200
 * </example>
31
201
 **/
32
202
 
33
203
#include <config.h>
270
440
gdata_calendar_service_query_events (GDataCalendarService *self, GDataCalendarCalendar *calendar, GDataQuery *query, GCancellable *cancellable,
271
441
                                     GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GError **error)
272
442
{
273
 
        /* TODO: Async variant */
274
443
        const gchar *uri;
275
444
 
276
445
        g_return_val_if_fail (GDATA_IS_CALENDAR_SERVICE (self), NULL);
301
470
}
302
471
 
303
472
/**
 
473
 * gdata_calendar_service_query_events_async: (skip)
 
474
 * @self: a #GDataCalendarService
 
475
 * @calendar: a #GDataCalendarCalendar
 
476
 * @query: (allow-none): a #GDataQuery with the query parameters, or %NULL
 
477
 * @cancellable: optional #GCancellable object, or %NULL
 
478
 * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
 
479
 * @progress_user_data: (closure): data to pass to the @progress_callback function
 
480
 * @callback: a #GAsyncReadyCallback to call when the query is finished
 
481
 * @user_data: (closure): data to pass to the @callback function
 
482
 *
 
483
 * Queries the service to return a list of events in the given @calendar, which match @query. @self, @calendar and @query are all reffed when this
 
484
 * function is called, so can safely be unreffed after this function returns.
 
485
 *
 
486
 * Get the results of the query using gdata_service_query_finish() in the @callback.
 
487
 *
 
488
 * For more details, see gdata_calendar_service_query_events(), which is the synchronous version of this function, and gdata_service_query_async(),
 
489
 * which is the base asynchronous query function.
 
490
 *
 
491
 * Since: 0.8.0
 
492
 **/
 
493
void
 
494
gdata_calendar_service_query_events_async (GDataCalendarService *self, GDataCalendarCalendar *calendar, GDataQuery *query, GCancellable *cancellable,
 
495
                                           GDataQueryProgressCallback progress_callback, gpointer progress_user_data,
 
496
                                           GAsyncReadyCallback callback, gpointer user_data)
 
497
{
 
498
        const gchar *uri;
 
499
 
 
500
        g_return_if_fail (GDATA_IS_CALENDAR_SERVICE (self));
 
501
        g_return_if_fail (GDATA_IS_CALENDAR_CALENDAR (calendar));
 
502
        g_return_if_fail (query == NULL || GDATA_IS_QUERY (query));
 
503
        g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 
504
        g_return_if_fail (callback != NULL);
 
505
 
 
506
        /* Ensure we're authenticated first */
 
507
        if (gdata_service_is_authenticated (GDATA_SERVICE (self)) == FALSE) {
 
508
                g_simple_async_report_error_in_idle (G_OBJECT (self), callback, user_data,
 
509
                                                     GDATA_SERVICE_ERROR, GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED,
 
510
                                                     _("You must be authenticated to query your own calendars."));
 
511
                return;
 
512
        }
 
513
 
 
514
        /* Use the calendar's content src */
 
515
        uri = gdata_entry_get_content_uri (GDATA_ENTRY (calendar));
 
516
        if (uri == NULL) {
 
517
                /* Erroring out is probably the safest thing to do */
 
518
                g_simple_async_report_error_in_idle (G_OBJECT (self), callback, user_data, GDATA_SERVICE_ERROR, GDATA_SERVICE_ERROR_PROTOCOL_ERROR,
 
519
                                                     _("The calendar did not have a content URI."));
 
520
                return;
 
521
        }
 
522
 
 
523
        /* Execute the query */
 
524
        gdata_service_query_async (GDATA_SERVICE (self), uri, query, GDATA_TYPE_CALENDAR_EVENT, cancellable, progress_callback, progress_user_data,
 
525
                                   callback, user_data);
 
526
}
 
527
 
 
528
/**
304
529
 * gdata_calendar_service_insert_event:
305
530
 * @self: a #GDataCalendarService
306
531
 * @event: the #GDataCalendarEvent to insert
318
543
GDataCalendarEvent *
319
544
gdata_calendar_service_insert_event (GDataCalendarService *self, GDataCalendarEvent *event, GCancellable *cancellable, GError **error)
320
545
{
321
 
        /* TODO: Async variant */
322
546
        /* TODO: How do we choose which calendar? */
323
547
        gchar *uri;
324
548
        GDataEntry *entry;
334
558
 
335
559
        return GDATA_CALENDAR_EVENT (entry);
336
560
}
 
561
 
 
562
/**
 
563
 * gdata_calendar_service_insert_event_async:
 
564
 * @self: a #GDataCalendarService
 
565
 * @event: the #GDataCalendarEvent to insert
 
566
 * @cancellable: optional #GCancellable object, or %NULL
 
567
 * @callback: a #GAsyncReadyCallback to call when insertion is finished
 
568
 * @user_data: (closure): data to pass to the @callback function
 
569
 *
 
570
 * Inserts @event by uploading it to the online calendar service. @self and @event are both reffed when this function is called, so can safely be
 
571
 * unreffed after this function returns.
 
572
 *
 
573
 * @callback should call gdata_service_insert_entry_finish() to obtain a #GDataCalendarEvent representing the inserted event and to check for possible
 
574
 * errors.
 
575
 *
 
576
 * For more details, see gdata_calendar_service_insert_event(), which is the synchronous version of this function, and
 
577
 * gdata_service_insert_entry_async(), which is the base asynchronous insertion function.
 
578
 *
 
579
 * Since: 0.8.0
 
580
 **/
 
581
void
 
582
gdata_calendar_service_insert_event_async (GDataCalendarService *self, GDataCalendarEvent *event, GCancellable *cancellable,
 
583
                                           GAsyncReadyCallback callback, gpointer user_data)
 
584
{
 
585
        gchar *uri;
 
586
 
 
587
        g_return_if_fail (GDATA_IS_CALENDAR_SERVICE (self));
 
588
        g_return_if_fail (GDATA_IS_CALENDAR_EVENT (event));
 
589
        g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 
590
 
 
591
        uri = g_strconcat (_gdata_service_get_scheme (), "://www.google.com/calendar/feeds/default/private/full", NULL);
 
592
        gdata_service_insert_entry_async (GDATA_SERVICE (self), uri, GDATA_ENTRY (event), cancellable, callback, user_data);
 
593
        g_free (uri);
 
594
}