GDataCalendarService

## GDataCalendarService GDataCalendarService — GData Calendar service object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataCalendarService;
                        GDataCalendarServiceClass;
    GDataCalendarService * gdata_calendar_service_new       (GDataAuthorizer *authorizer);
    GDataAuthorizationDomain * gdata_calendar_service_get_primary_authorization_domain
                                                            (void);
    GDataFeed *         gdata_calendar_service_query_all_calendars
                                                            (GDataCalendarService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_calendar_service_query_all_calendars_async
                                                            (GDataCalendarService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GDestroyNotify destroy_progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataFeed *         gdata_calendar_service_query_own_calendars
                                                            (GDataCalendarService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_calendar_service_query_own_calendars_async
                                                            (GDataCalendarService *self,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GDestroyNotify destroy_progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataFeed *         gdata_calendar_service_query_events (GDataCalendarService *self,
                                                             GDataCalendarCalendar *calendar,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_calendar_service_query_events_async
                                                            (GDataCalendarService *self,
                                                             GDataCalendarCalendar *calendar,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GDestroyNotify destroy_progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataCalendarEvent * gdata_calendar_service_insert_event
                                                            (GDataCalendarService *self,
                                                             GDataCalendarEvent *event,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_calendar_service_insert_event_async
                                                            (GDataCalendarService *self,
                                                             GDataCalendarEvent *event,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----GDataService
             +----GDataCalendarService

## Implemented Interfaces

GDataCalendarService implements GDataBatchable.

## Description

GDataCalendarService is a subclass of GDataService for communicating with the GData API of Google Calendar. It supports querying for, inserting, editing and deleting events from calendars, as well as operations on the calendars themselves.

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

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 which users the calendar is shared with. For more information about ACLs for calendars, see the online documentation on sharing calendars.

Example 15. Retrieving the Access Control List for a Calendar

    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
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    GDataCalendarService *service;
    GDataCalendarCalendar *calendar;
    GDataFeed *acl_feed;
    GDataAccessRule *rule, *new_rule;
    GDataLink *acl_link;
    GList *i;
    GError *error = NULL;

    /* Create a service and retrieve a calendar to work on */
    service = create_calendar_service ();
    calendar = get_calendar (service);

    /* Query the service for the ACL for the given calendar */
    acl_feed = gdata_access_handler_get_rules (GDATA_ACCESS_HANDLER (calendar), GDATA_SERVICE (service), NULL, NULL, NULL, &error);

    if (error != NULL) {
        g_error ("Error getting ACL feed for calendar: %s", error->message);
        g_error_free (error);
        g_object_unref (calendar);
        g_object_unref (service);
        return;
    }

    /* Iterate through the ACL */
    for (i = gdata_feed_get_entries (acl_feed); i != NULL; i = i->next) {
        const gchar *scope_value;

        rule = GDATA_ACCESS_RULE (i->data);

        /* Do something with the access rule here. As an example, we update the rule applying to test@gmail.com and delete all
         * the other rules. We then insert another rule for example@gmail.com below. */
        gdata_access_rule_get_scope (rule, NULL, &scope_value);
        if (scope_value != NULL && strcmp (scope_value, "test@gmail.com") == 0) {
            GDataAccessRule *updated_rule;

            /* Update the rule to make test@gmail.com an editor (full read/write access to the calendar, but they can't change
             * the ACL). */
            gdata_access_rule_set_role (rule, GDATA_CALENDAR_ACCESS_ROLE_EDITOR);
            updated_rule = GDATA_ACCESS_RULE (gdata_service_update_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error));

            if (error != NULL) {
                g_error ("Error updating access rule for %s: %s", scope_value, error->message);
                g_error_free (error);
                g_object_unref (acl_feed);
                g_object_unref (calendar);
                g_object_unref (service);
                return;
            }

            g_object_unref (updated_rule);
        } else {
            /* Delete any rule which doesn't apply to test@gmail.com */
            gdata_service_delete_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error);

            if (error != NULL) {
                g_error ("Error deleting access rule for %s: %s", scope_value, error->message);
                g_error_free (error);
                g_object_unref (acl_feed);
                g_object_unref (calendar);
                g_object_unref (service);
                return;
            }
        }
    }

    g_object_unref (acl_feed);

    /* Create and insert a new access rule for example@gmail.com which allows them to view free/busy information for events in the
     * calendar, but doesn't allow them to view the full event details. */
    rule = gdata_access_rule_new (NULL);
    gdata_access_rule_set_role (rule, GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY);
    gdata_access_rule_set_scope (rule, GDATA_ACCESS_SCOPE_USER, "example@gmail.com");

    acl_link = gdata_entry_look_up_link (GDATA_ENTRY (calendar), GDATA_LINK_ACCESS_CONTROL_LIST);
    new_rule = GDATA_ACCESS_RULE (gdata_service_insert_entry (GDATA_SERVICE (service), gdata_link_get_uri (acl_link), GDATA_ENTRY (rule),
                                                              NULL, &error));

    g_object_unref (rule);
    g_object_unref (calendar);
    g_object_unref (service);

    if (error != NULL) {
        g_error ("Error inserting access rule: %s", error->message);
        g_error_free (error);
        return;
    }

    g_object_unref (acl_link);

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

Example 16. Performing a Batch Operation on a Calendar

    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
    61
    GDataCalendarService *service;
    GDataCalendarCalendar *calendar;
    GDataBatchOperation *operation;
    GDataLink *batch_link;
    GList *i;
    GError *error = NULL;

    /* Create a service and retrieve a calendar to work on */
    service = create_calendar_service ();
    calendar = get_calendar (service);

    /* Create the batch operation */
    batch_link = gdata_entry_look_up_link (GDATA_ENTRY (calendar), GDATA_LINK_BATCH);
    operation = gdata_batchable_create_operation (GDATA_BATCHABLE (service), gdata_link_get_uri (batch_link));

    g_object_unref (calendar);

    gdata_batch_operation_add_query (operation, event_entry_id_to_query, GDATA_TYPE_CALENDAR_EVENT,
                                     (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

### GDataCalendarService

    typedef struct _GDataCalendarService GDataCalendarService;

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

### GDataCalendarServiceClass

    typedef struct {
    } GDataCalendarServiceClass;

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

### gdata_calendar_service_new ()

    GDataCalendarService * gdata_calendar_service_new       (GDataAuthorizer *authorizer);

Creates a new GDataCalendarService 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 GDataCalendarService, or `NULL`; unref with `g_object_unref()`

Since 0.9.0

### gdata_calendar_service_get_primary_authorization_domain ()

    GDataAuthorizationDomain * gdata_calendar_service_get_primary_authorization_domain
                                                            (void);

The primary GDataAuthorizationDomain for interacting with Google Calendar. This will not normally need to be used, as it's used internally by the GDataCalendarService 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_calendar_service_query_all_calendars ()

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

Queries the service to return a list of all calendars from the authenticated account which match the given `query`. It will return all calendars the user has read access to, including primary, secondary and imported calendars.

For more details, see `gdata_service_query()`.

`self` : | a GDataCalendarService
`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]

### gdata_calendar_service_query_all_calendars_async ()

    void                gdata_calendar_service_query_all_calendars_async
                                                            (GDataCalendarService *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 all calendars from the authenticated account which match 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_calendar_service_query_all_calendars()`, which is the synchronous version of this function, and `gdata_service_query_async()`, which is the base asynchronous query function.

`self` : | a GDataCalendarService
`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 authentication is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.9.1

### gdata_calendar_service_query_own_calendars ()

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

Queries the service to return a list of calendars from the authenticated account which match the given `query`, and the authenticated user owns. (i.e. They have full read/write access to the calendar, as well as the ability to set permissions on the calendar.)

For more details, see `gdata_service_query()`.

`self` : | a GDataCalendarService
`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]

### gdata_calendar_service_query_own_calendars_async ()

    void                gdata_calendar_service_query_own_calendars_async
                                                            (GDataCalendarService *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 calendars from the authenticated account which match the given `query`, and the authenticated user owns. `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_calendar_service_query_own_calendars()`, which is the synchronous version of this function, and `gdata_service_query_async()`, which is the base asynchronous query function.

`self` : | a GDataCalendarService
`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 authentication is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.9.1

### gdata_calendar_service_query_events ()

    GDataFeed *         gdata_calendar_service_query_events (GDataCalendarService *self,
                                                             GDataCalendarCalendar *calendar,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);

Queries the service to return a list of events in the given `calendar`, which match `query`.

For more details, see `gdata_service_query()`.

`self` : | a GDataCalendarService
`calendar` : | a GDataCalendarCalendar
`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]

### gdata_calendar_service_query_events_async ()

    void                gdata_calendar_service_query_events_async
                                                            (GDataCalendarService *self,
                                                             GDataCalendarCalendar *calendar,
                                                             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 events in the given `calendar`, which match `query`. `self`, `calendar` and `query` are all reffed when this function is called, so can safely be unreffed after this function returns.

Get the results of the query using `gdata_service_query_finish()` in the `callback`.

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

`self` : | a GDataCalendarService
`calendar` : | a GDataCalendarCalendar
`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_calendar_service_insert_event ()

    GDataCalendarEvent * gdata_calendar_service_insert_event
                                                            (GDataCalendarService *self,
                                                             GDataCalendarEvent *event,
                                                             GCancellable *cancellable,
                                                             GError **error);

Inserts `event` by uploading it to the online calendar service.

For more details, see `gdata_service_insert_entry()`.

`self` : | a GDataCalendarService
`event` : | the GDataCalendarEvent to insert
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | a GError, or `NULL`
Returns : | an updated GDataCalendarEvent, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.2.0

### gdata_calendar_service_insert_event_async ()

    void                gdata_calendar_service_insert_event_async
                                                            (GDataCalendarService *self,
                                                             GDataCalendarEvent *event,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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 unreffed after this function returns.

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

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

`self` : | a GDataCalendarService
`event` : | the GDataCalendarEvent 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.8.0