GDataCalendarCalendar

## GDataCalendarCalendar GDataCalendarCalendar — GData Calendar calendar object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

    #define             GDATA_CALENDAR_ACCESS_ROLE_READ
    #define             GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY
    #define             GDATA_CALENDAR_ACCESS_ROLE_EDITOR
    #define             GDATA_CALENDAR_ACCESS_ROLE_OWNER
    #define             GDATA_CALENDAR_ACCESS_ROLE_ROOT
                        GDataCalendarCalendar;
                        GDataCalendarCalendarClass;
    GDataCalendarCalendar * gdata_calendar_calendar_new     (const gchar *id);
    void                gdata_calendar_calendar_get_color   (GDataCalendarCalendar *self,
                                                             GDataColor *color);
    void                gdata_calendar_calendar_set_color   (GDataCalendarCalendar *self,
                                                             const GDataColor *color);
    gboolean            gdata_calendar_calendar_is_hidden   (GDataCalendarCalendar *self);
    void                gdata_calendar_calendar_set_is_hidden
                                                            (GDataCalendarCalendar *self,
                                                             gboolean is_hidden);
    gboolean            gdata_calendar_calendar_is_selected (GDataCalendarCalendar *self);
    void                gdata_calendar_calendar_set_is_selected
                                                            (GDataCalendarCalendar *self,
                                                             gboolean is_selected);
    const gchar *       gdata_calendar_calendar_get_timezone
                                                            (GDataCalendarCalendar *self);
    void                gdata_calendar_calendar_set_timezone
                                                            (GDataCalendarCalendar *self,
                                                             const gchar *_timezone);
    gint64              gdata_calendar_calendar_get_edited  (GDataCalendarCalendar *self);
    guint               gdata_calendar_calendar_get_times_cleaned
                                                            (GDataCalendarCalendar *self);
    const gchar *       gdata_calendar_calendar_get_access_level
                                                            (GDataCalendarCalendar *self);

## Object Hierarchy

      GObject
       +----GDataParsable
             +----GDataEntry
                   +----GDataCalendarCalendar

## Implemented Interfaces

GDataCalendarCalendar implements GDataAccessHandler.

## Properties

      "access-level"             gchar*                : Read
      "color"                    GDataColor*           : Read / Write
      "edited"                   gint64                : Read
      "is-hidden"                gboolean              : Read / Write
      "is-selected"              gboolean              : Read / Write
      "times-cleaned"            guint                 : Read
      "timezone"                 gchar*                : Read / Write

## Description

GDataCalendarCalendar is a subclass of GDataEntry to represent a calendar from Google Calendar.

GDataCalendarCalendar implements GDataAccessHandler, meaning the access rules to it can be modified using that interface. As well as the access roles defined for the base GDataAccessRule (e.g. `GDATA_ACCESS_ROLE_NONE`), GDataCalendarCalendar has its own, such as `GDATA_CALENDAR_ACCESS_ROLE_EDITOR` and `GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY`.

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

Example 12. Listing Calendars

    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
    GDataCalendarService *service;
    GDataFeed *feed;
    GList *i;
    GError *error = NULL;

    /* Create a service */
    service = create_calendar_service ();

    /* Query for all of the calendars the currently authenticated user has access to, including those which they have read-only
     * access to. */
    feed = gdata_calendar_service_query_all_calendars (service, NULL, NULL, NULL, NULL, &error);

    g_object_unref (service);

    if (error != NULL) {
        g_error ("Error querying for calendars: %s", error->message);
        g_error_free (error);
        return;
    }

    /* Iterate through the returned calendars and do something with them */
    for (i = gdata_feed_get_entries (feed); i != NULL; i = i->next) {
        const gchar *access_level;
        gboolean has_write_access;
        GDataCalendarCalendar *calendar = GDATA_CALENDAR_CALENDAR (i->data);

        /* Determine whether we have write access to the calendar, or just read-only or free/busy access. Note that the access levels
         * are more detailed than this; see the documentation for gdata_calendar_calendar_get_access_level() for more information. */
        access_level = gdata_calendar_calendar_get_access_level (calendar);
        has_write_access = (access_level != NULL && strcmp (access_level, GDATA_CALENDAR_ACCESS_ROLE_EDITOR) == 0) ? TRUE : FALSE;

        /* Do something with the calendar here, such as insert it into a UI */
    }

    g_object_unref (feed);

## Details

### GDATA_CALENDAR_ACCESS_ROLE_READ

    #define GDATA_CALENDAR_ACCESS_ROLE_READ "http://schemas.google.com/gCal/2005#read"

The users specified by the GDataAccessRule have read-only access to the calendar.

Since 0.7.0

### GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY

    #define GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY "http://schemas.google.com/gCal/2005#freebusy"

The users specified by the GDataAccessRule can only see the free/busy information on the calendar; not event details.

Since 0.7.0

### GDATA_CALENDAR_ACCESS_ROLE_EDITOR

    #define GDATA_CALENDAR_ACCESS_ROLE_EDITOR "http://schemas.google.com/gCal/2005#editor"

The users specified by the GDataAccessRule have full edit access to the calendar, except they can't change the calendar's access rules.

Since 0.7.0

### GDATA_CALENDAR_ACCESS_ROLE_OWNER

    #define GDATA_CALENDAR_ACCESS_ROLE_OWNER "http://schemas.google.com/gCal/2005#owner"

The users specified by the GDataAccessRule have full owner access to the calendar.

Since 0.7.0

### GDATA_CALENDAR_ACCESS_ROLE_ROOT

    #define GDATA_CALENDAR_ACCESS_ROLE_ROOT "http://schemas.google.com/gCal/2005#root"

The users specified by the GDataAccessRule have full administrator access to the calendar server. This is only available in Google Apps For Your Domain.

Since 0.7.0

### GDataCalendarCalendar

    typedef struct _GDataCalendarCalendar GDataCalendarCalendar;

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

### GDataCalendarCalendarClass

    typedef struct {
    } GDataCalendarCalendarClass;

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

### gdata_calendar_calendar_new ()

    GDataCalendarCalendar * gdata_calendar_calendar_new     (const gchar *id);

Creates a new GDataCalendarCalendar with the given ID and default properties.

`id` : | the calendar's ID, or `NULL`. [allow-none]
Returns : | a new GDataCalendarCalendar; unref with `g_object_unref()`

### gdata_calendar_calendar_get_color ()

    void                gdata_calendar_calendar_get_color   (GDataCalendarCalendar *self,
                                                             GDataColor *color);

Gets the "color" property and puts it in `color`.

`self` : | a GDataCalendarCalendar
`color` : | a GDataColor. [out caller-allocates]

### gdata_calendar_calendar_set_color ()

    void                gdata_calendar_calendar_set_color   (GDataCalendarCalendar *self,
                                                             const GDataColor *color);

Sets the "color" property to `color`.

`self` : | a GDataCalendarCalendar
`color` : | a new GDataColor

### gdata_calendar_calendar_is_hidden ()

    gboolean            gdata_calendar_calendar_is_hidden   (GDataCalendarCalendar *self);

Gets the "is-hidden" property.

`self` : | a GDataCalendarCalendar
Returns : | `TRUE` if the calendar is hidden, `FALSE` otherwise

Since 0.2.0

### gdata_calendar_calendar_set_is_hidden ()

    void                gdata_calendar_calendar_set_is_hidden
                                                            (GDataCalendarCalendar *self,
                                                             gboolean is_hidden);

Sets the "is-hidden" property to `is_hidden`.

`self` : | a GDataCalendarCalendar
`is_hidden` : | `TRUE` to hide the calendar, `FALSE` otherwise

Since 0.2.0

### gdata_calendar_calendar_is_selected ()

    gboolean            gdata_calendar_calendar_is_selected (GDataCalendarCalendar *self);

Gets the "is-selected" property.

`self` : | a GDataCalendarCalendar
Returns : | `TRUE` if the calendar is selected, `FALSE` otherwise

Since 0.2.0

### gdata_calendar_calendar_set_is_selected ()

    void                gdata_calendar_calendar_set_is_selected
                                                            (GDataCalendarCalendar *self,
                                                             gboolean is_selected);

Sets the "is-selected" property to `is_selected`.

`self` : | a GDataCalendarCalendar
`is_selected` : | `TRUE` to select the calendar, `FALSE` otherwise

Since 0.2.0

### gdata_calendar_calendar_get_timezone ()

    const gchar *       gdata_calendar_calendar_get_timezone
                                                            (GDataCalendarCalendar *self);

Gets the "timezone" property.

`self` : | a GDataCalendarCalendar
Returns : | the calendar's timezone, or `NULL`

### gdata_calendar_calendar_set_timezone ()

    void                gdata_calendar_calendar_set_timezone
                                                            (GDataCalendarCalendar *self,
                                                             const gchar *_timezone);

Sets the "timezone" property to the new timezone, `_timezone`.

Set `_timezone` to `NULL` to unset the property in the calendar.

`self` : | a GDataCalendarCalendar
`_timezone` : | a new timezone, or `NULL`. [allow-none]

### gdata_calendar_calendar_get_edited ()

    gint64              gdata_calendar_calendar_get_edited  (GDataCalendarCalendar *self);

Gets the "edited" property. If the property is unset, `-1` will be returned.

`self` : | a GDataCalendarCalendar
Returns : | the UNIX timestamp for the time the calendar was last edited, or `-1`

### gdata_calendar_calendar_get_times_cleaned ()

    guint               gdata_calendar_calendar_get_times_cleaned
                                                            (GDataCalendarCalendar *self);

Gets the "times-cleaned" property.

`self` : | a GDataCalendarCalendar
Returns : | the number of times the calendar has been totally emptied

### gdata_calendar_calendar_get_access_level ()

    const gchar *       gdata_calendar_calendar_get_access_level
                                                            (GDataCalendarCalendar *self);

Gets the "access-level" property.

`self` : | a GDataCalendarCalendar
Returns : | the authenticated user's access level to the calendar, or `NULL`

## Property Details

### The `"access-level"` property

      "access-level"             gchar*                : Read

Indicates the access level the current user has to the calendar. For example: `GDATA_CALENDAR_ACCESS_ROLE_READ` or `GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY`. The "current user" is the one logged in with `gdata_service_authenticate()` or the guest user.

Default value: NULL

### The `"color"` property

      "color"                    GDataColor*           : Read / Write

The color used to highlight the calendar in the user's browser.

### The `"edited"` property

      "edited"                   gint64                : Read

The last time the calendar was edited. If the calendar has not been edited yet, the content indicates the time it was created.

For more information, see the Atom Publishing Protocol specification.

Allowed values: >= -1

Default value: -1

### The `"is-hidden"` property

      "is-hidden"                gboolean              : Read / Write

Indicates whether the calendar is visible.

Default value: FALSE

Since 0.2.0

### The `"is-selected"` property

      "is-selected"              gboolean              : Read / Write

Indicates whether the calendar is selected.

Default value: FALSE

Since 0.2.0

### The `"times-cleaned"` property

      "times-cleaned"            guint                 : Read

The number of times the calendar has been cleared of events.

Default value: 0

### The `"timezone"` property

      "timezone"                 gchar*                : Read / Write

The timezone in which the calendar's times are given. This is a timezone name in tz database notation: reference.

Default value: NULL