GDataCalendarEvent

## GDataCalendarEvent GDataCalendarEvent — GData Calendar event object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataCalendarEvent;
                        GDataCalendarEventClass;
    GDataCalendarEvent * gdata_calendar_event_new           (const gchar *id);
    GList *             gdata_calendar_event_get_people     (GDataCalendarEvent *self);
    void                gdata_calendar_event_add_person     (GDataCalendarEvent *self,
                                                             GDataGDWho *who);
    GList *             gdata_calendar_event_get_places     (GDataCalendarEvent *self);
    void                gdata_calendar_event_add_place      (GDataCalendarEvent *self,
                                                             GDataGDWhere *where);
    GList *             gdata_calendar_event_get_times      (GDataCalendarEvent *self);
    gboolean            gdata_calendar_event_get_primary_time
                                                            (GDataCalendarEvent *self,
                                                             gint64 *start_time,
                                                             gint64 *end_time,
                                                             GDataGDWhen **when);
    void                gdata_calendar_event_add_time       (GDataCalendarEvent *self,
                                                             GDataGDWhen *when);
    const gchar *       gdata_calendar_event_get_recurrence (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_recurrence (GDataCalendarEvent *self,
                                                             const gchar *recurrence);
    void                gdata_calendar_event_get_original_event_details
                                                            (GDataCalendarEvent *self,
                                                             gchar **event_id,
                                                             gchar **event_uri);
    gboolean            gdata_calendar_event_is_exception   (GDataCalendarEvent *self);
    gboolean            gdata_calendar_event_get_anyone_can_add_self
                                                            (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_anyone_can_add_self
                                                            (GDataCalendarEvent *self,
                                                             gboolean anyone_can_add_self);
    gboolean            gdata_calendar_event_get_guests_can_invite_others
                                                            (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_guests_can_invite_others
                                                            (GDataCalendarEvent *self,
                                                             gboolean guests_can_invite_others);
    gboolean            gdata_calendar_event_get_guests_can_modify
                                                            (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_guests_can_modify
                                                            (GDataCalendarEvent *self,
                                                             gboolean guests_can_modify);
    gboolean            gdata_calendar_event_get_guests_can_see_guests
                                                            (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_guests_can_see_guests
                                                            (GDataCalendarEvent *self,
                                                             gboolean guests_can_see_guests);
    guint               gdata_calendar_event_get_sequence   (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_sequence   (GDataCalendarEvent *self,
                                                             guint sequence);
    const gchar *       gdata_calendar_event_get_status     (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_status     (GDataCalendarEvent *self,
                                                             const gchar *status);
    const gchar *       gdata_calendar_event_get_transparency
                                                            (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_transparency
                                                            (GDataCalendarEvent *self,
                                                             const gchar *transparency);
    const gchar *       gdata_calendar_event_get_uid        (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_uid        (GDataCalendarEvent *self,
                                                             const gchar *uid);
    const gchar *       gdata_calendar_event_get_visibility (GDataCalendarEvent *self);
    void                gdata_calendar_event_set_visibility (GDataCalendarEvent *self,
                                                             const gchar *visibility);
    gint64              gdata_calendar_event_get_edited     (GDataCalendarEvent *self);

## Object Hierarchy

      GObject
       +----GDataParsable
             +----GDataEntry
                   +----GDataCalendarEvent

## Properties

      "anyone-can-add-self"      gboolean              : Read / Write
      "edited"                   gint64                : Read
      "guests-can-invite-others" gboolean              : Read / Write
      "guests-can-modify"        gboolean              : Read / Write
      "guests-can-see-guests"    gboolean              : Read / Write
      "original-event-id"        gchar*                : Read
      "original-event-uri"       gchar*                : Read
      "recurrence"               gchar*                : Read / Write
      "sequence"                 guint                 : Read / Write
      "status"                   gchar*                : Read / Write
      "transparency"             gchar*                : Read / Write
      "uid"                      gchar*                : Read / Write
      "visibility"               gchar*                : Read / Write

## Description

GDataCalendarEvent is a subclass of GDataEntry to represent an event on a calendar from Google Calendar.

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

Example 19. Adding a New Event to the Default 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
    GDataCalendarService *service;
    GDataCalendarEvent *event, *new_event;
    GDataGDWhere *where;
    GDataGDWho *who;
    GDataGDWhen *when;
    GTimeVal current_time;
    GError *error = NULL;

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

    /* Create the new event */
    event = gdata_calendar_event_new (NULL);

    gdata_entry_set_title (GDATA_ENTRY (event), "Event Title");
    gdata_entry_set_content (GDATA_ENTRY (event), "Event description. This should be a few sentences long.");
    gdata_calendar_event_set_status (event, GDATA_GD_EVENT_STATUS_CONFIRMED);

    where = gdata_gd_where_new (NULL, "Description of the location", NULL);
    gdata_calendar_event_add_place (event, where);
    g_object_unref (where);

    who = gdata_gd_who_new (GDATA_GD_WHO_EVENT_ORGANIZER, "John Smith", "john.smith@gmail.com");
    gdata_calendar_event_add_person (event, who);
    g_object_unref (who);

    g_get_current_time (&current_time);
    when = gdata_gd_when_new (current_time.tv_sec, current_time.tv_sec + 3600, FALSE);
    gdata_calendar_event_add_time (event, when);
    g_object_unref (when);

    /* Insert the event in the calendar */
    new_event = gdata_calendar_service_insert_event (service, event, NULL, &error);

    g_object_unref (event);
    g_object_unref (service);

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

    /* Do something with the new_event here, such as return it to the user or store its ID for later usage */

    g_object_unref (new_event);

## Details

### GDataCalendarEvent

    typedef struct _GDataCalendarEvent GDataCalendarEvent;

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

### GDataCalendarEventClass

    typedef struct {
    } GDataCalendarEventClass;

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

### gdata_calendar_event_new ()

    GDataCalendarEvent * gdata_calendar_event_new           (const gchar *id);

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

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

### gdata_calendar_event_get_people ()

    GList *             gdata_calendar_event_get_people     (GDataCalendarEvent *self);

Gets a list of the people attending the event.

`self` : | a GDataCalendarEvent
Returns : | a GList of GDataGDWhos, or `NULL`. [element-type GData.GDWho][transfer none]

Since 0.2.0

### gdata_calendar_event_add_person ()

    void                gdata_calendar_event_add_person     (GDataCalendarEvent *self,
                                                             GDataGDWho *who);

Adds the person `who` to the event as a guest (attendee, organiser, performer, etc.), and increments its reference count.

Duplicate people will not be added to the list.

`self` : | a GDataCalendarEvent
`who` : | a GDataGDWho to add

### gdata_calendar_event_get_places ()

    GList *             gdata_calendar_event_get_places     (GDataCalendarEvent *self);

Gets a list of the locations associated with the event.

`self` : | a GDataCalendarEvent
Returns : | a GList of GDataGDWheres, or `NULL`. [element-type GData.GDWhere][transfer none]

Since 0.2.0

### gdata_calendar_event_add_place ()

    void                gdata_calendar_event_add_place      (GDataCalendarEvent *self,
                                                             GDataGDWhere *where);

Adds the place `where` to the event as a location and increments its reference count.

Duplicate places will not be added to the list.

`self` : | a GDataCalendarEvent
`where` : | a GDataGDWhere to add

### gdata_calendar_event_get_times ()

    GList *             gdata_calendar_event_get_times      (GDataCalendarEvent *self);

Gets a list of the time periods associated with the event.

`self` : | a GDataCalendarEvent
Returns : | a GList of GDataGDWhens, or `NULL`. [element-type GData.GDWhen][transfer none]

Since 0.2.0

### gdata_calendar_event_get_primary_time ()

    gboolean            gdata_calendar_event_get_primary_time
                                                            (GDataCalendarEvent *self,
                                                             gint64 *start_time,
                                                             gint64 *end_time,
                                                             GDataGDWhen **when);

Gets the first time period associated with the event, conveniently returning just its start and end times if required.

If there are no time periods, or more than one time period, associated with the event, `FALSE` will be returned, and the parameters will remain unmodified.

`self` : | a GDataCalendarEvent
`start_time` : | a gint64 for the start time, or `NULL`. [out caller-allocates]
`end_time` : | a gint64 for the end time, or `NULL`. [out caller-allocates]
`when` : | a GDataGDWhen for the primary time structure, or `NULL`. [out callee-allocates][transfer none]
Returns : | `TRUE` if there is only one time period associated with the event, `FALSE` otherwise

Since 0.2.0

### gdata_calendar_event_add_time ()

    void                gdata_calendar_event_add_time       (GDataCalendarEvent *self,
                                                             GDataGDWhen *when);

Adds `when` to the event as a time period when the event happens, and increments its reference count.

Duplicate times will not be added to the list.

`self` : | a GDataCalendarEvent
`when` : | a GDataGDWhen to add

Since 0.2.0

### gdata_calendar_event_get_recurrence ()

    const gchar *       gdata_calendar_event_get_recurrence (GDataCalendarEvent *self);

Gets the "recurrence" property.

`self` : | a GDataCalendarEvent
Returns : | the event recurrence patterns, or `NULL`

Since 0.3.0

### gdata_calendar_event_set_recurrence ()

    void                gdata_calendar_event_set_recurrence (GDataCalendarEvent *self,
                                                             const gchar *recurrence);

Sets the "recurrence" property to the new recurrence, `recurrence`.

Set `recurrence` to `NULL` to unset the property in the event.

`self` : | a GDataCalendarEvent
`recurrence` : | a new event recurrence, or `NULL`. [allow-none]

Since 0.3.0

### gdata_calendar_event_get_original_event_details ()

    void                gdata_calendar_event_get_original_event_details
                                                            (GDataCalendarEvent *self,
                                                             gchar **event_id,
                                                             gchar **event_uri);

Gets details of the original event, if this event is an exception to a recurring event. The original event's ID and the URI of the event's XML are returned in `event_id` and `event_uri`, respectively.

If this event is not an exception to a recurring event, `event_id` and `event_uri` will be set to `NULL`. See `gdata_calendar_event_is_exception()` to determine more simply whether an event is an exception to a recurring event.

If both `event_id` and `event_uri` are `NULL`, this function is a no-op. Otherwise, they should both be freed with `g_free()`.

`self` : | a GDataCalendarEvent
`event_id` : | return location for the original event's ID, or `NULL`. [out callee-allocates][transfer full]
`event_uri` : | return location for the original event's URI, or `NULL`. [out callee-allocates][transfer full]

Since 0.3.0

### gdata_calendar_event_is_exception ()

    gboolean            gdata_calendar_event_is_exception   (GDataCalendarEvent *self);

Determines whether the event is an exception to a recurring event. If it is, details of the original event can be retrieved using `gdata_calendar_event_get_original_event_details()`.

`self` : | a GDataCalendarEvent
Returns : | `TRUE` if the event is an exception, `FALSE` otherwise

Since 0.3.0

### gdata_calendar_event_get_anyone_can_add_self ()

    gboolean            gdata_calendar_event_get_anyone_can_add_self
                                                            (GDataCalendarEvent *self);

Gets the "anyone-can-add-self" property.

`self` : | a GDataCalendarEvent
Returns : | `TRUE` if anyone can add themselves as an attendee to the event, `FALSE` otherwise

### gdata_calendar_event_set_anyone_can_add_self ()

    void                gdata_calendar_event_set_anyone_can_add_self
                                                            (GDataCalendarEvent *self,
                                                             gboolean anyone_can_add_self);

Sets the "anyone-can-add-self" property to `anyone_can_add_self`.

`self` : | a GDataCalendarEvent
`anyone_can_add_self` : | `TRUE` if anyone can add themselves as an attendee to the event, `FALSE` otherwise

### gdata_calendar_event_get_guests_can_invite_others ()

    gboolean            gdata_calendar_event_get_guests_can_invite_others
                                                            (GDataCalendarEvent *self);

Gets the "guests-can-invite-others" property.

`self` : | a GDataCalendarEvent
Returns : | `TRUE` if attendees can invite others to the event, `FALSE` otherwise

### gdata_calendar_event_set_guests_can_invite_others ()

    void                gdata_calendar_event_set_guests_can_invite_others
                                                            (GDataCalendarEvent *self,
                                                             gboolean guests_can_invite_others);

Sets the "guests-can-invite-others" property to `guests_can_invite_others`.

`self` : | a GDataCalendarEvent
`guests_can_invite_others` : | `TRUE` if attendees can invite others to the event, `FALSE` otherwise

### gdata_calendar_event_get_guests_can_modify ()

    gboolean            gdata_calendar_event_get_guests_can_modify
                                                            (GDataCalendarEvent *self);

Gets the "guests-can-modify" property.

`self` : | a GDataCalendarEvent
Returns : | `TRUE` if attendees can modify the original event, `FALSE` otherwise

### gdata_calendar_event_set_guests_can_modify ()

    void                gdata_calendar_event_set_guests_can_modify
                                                            (GDataCalendarEvent *self,
                                                             gboolean guests_can_modify);

Sets the "guests-can-modify" property to `guests_can_modify`.

`self` : | a GDataCalendarEvent
`guests_can_modify` : | `TRUE` if attendees can modify the original event, `FALSE` otherwise

### gdata_calendar_event_get_guests_can_see_guests ()

    gboolean            gdata_calendar_event_get_guests_can_see_guests
                                                            (GDataCalendarEvent *self);

Gets the "guests-can-see-guests" property.

`self` : | a GDataCalendarEvent
Returns : | `TRUE` if attendees can see who's attending the event, `FALSE` otherwise

### gdata_calendar_event_set_guests_can_see_guests ()

    void                gdata_calendar_event_set_guests_can_see_guests
                                                            (GDataCalendarEvent *self,
                                                             gboolean guests_can_see_guests);

Sets the "guests-can-see-guests" property to `guests_can_see_guests`.

`self` : | a GDataCalendarEvent
`guests_can_see_guests` : | `TRUE` if attendees can see who's attending the event, `FALSE` otherwise

### gdata_calendar_event_get_sequence ()

    guint               gdata_calendar_event_get_sequence   (GDataCalendarEvent *self);

Gets the "sequence" property.

`self` : | a GDataCalendarEvent
Returns : | the event's sequence number

### gdata_calendar_event_set_sequence ()

    void                gdata_calendar_event_set_sequence   (GDataCalendarEvent *self,
                                                             guint sequence);

Sets the "sequence" property to the new sequence number, `sequence`.

`self` : | a GDataCalendarEvent
`sequence` : | a new sequence number, or `0`

### gdata_calendar_event_get_status ()

    const gchar *       gdata_calendar_event_get_status     (GDataCalendarEvent *self);

Gets the "status" property.

`self` : | a GDataCalendarEvent
Returns : | the event status, or `NULL`

Since 0.2.0

### gdata_calendar_event_set_status ()

    void                gdata_calendar_event_set_status     (GDataCalendarEvent *self,
                                                             const gchar *status);

Sets the "status" property to the new status, `status`.

Set `status` to `NULL` to unset the property in the event.

`self` : | a GDataCalendarEvent
`status` : | a new event status, or `NULL`. [allow-none]

Since 0.2.0

### gdata_calendar_event_get_transparency ()

    const gchar *       gdata_calendar_event_get_transparency
                                                            (GDataCalendarEvent *self);

Gets the "transparency" property.

`self` : | a GDataCalendarEvent
Returns : | the event transparency, or `NULL`

### gdata_calendar_event_set_transparency ()

    void                gdata_calendar_event_set_transparency
                                                            (GDataCalendarEvent *self,
                                                             const gchar *transparency);

Sets the "transparency" property to the new transparency, `transparency`.

Set `transparency` to `NULL` to unset the property in the event.

`self` : | a GDataCalendarEvent
`transparency` : | a new event transparency, or `NULL`. [allow-none]

### gdata_calendar_event_get_uid ()

    const gchar *       gdata_calendar_event_get_uid        (GDataCalendarEvent *self);

Gets the "uid" property.

`self` : | a GDataCalendarEvent
Returns : | the event's UID, or `NULL`

### gdata_calendar_event_set_uid ()

    void                gdata_calendar_event_set_uid        (GDataCalendarEvent *self,
                                                             const gchar *uid);

Sets the "uid" property to the new UID, `uid`.

Set `uid` to `NULL` to unset the property in the event.

`self` : | a GDataCalendarEvent
`uid` : | a new event UID, or `NULL`. [allow-none]

### gdata_calendar_event_get_visibility ()

    const gchar *       gdata_calendar_event_get_visibility (GDataCalendarEvent *self);

Gets the "visibility" property.

`self` : | a GDataCalendarEvent
Returns : | the event visibility, or `NULL`

### gdata_calendar_event_set_visibility ()

    void                gdata_calendar_event_set_visibility (GDataCalendarEvent *self,
                                                             const gchar *visibility);

Sets the "visibility" property to the new visibility, `visibility`.

Set `visibility` to `NULL` to unset the property in the event.

`self` : | a GDataCalendarEvent
`visibility` : | a new event visibility, or `NULL`. [allow-none]

### gdata_calendar_event_get_edited ()

    gint64              gdata_calendar_event_get_edited     (GDataCalendarEvent *self);

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

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

## Property Details

### The `"anyone-can-add-self"` property

      "anyone-can-add-self"      gboolean              : Read / Write

Indicates whether anyone can invite themselves to the event, by adding themselves to the attendee list.

Default value: FALSE

### The `"edited"` property

      "edited"                   gint64                : Read

The last time the event was edited. If the event 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 `"guests-can-invite-others"` property

      "guests-can-invite-others" gboolean              : Read / Write

Indicates whether attendees may invite others to the event.

For more information, see the GData specification.

Default value: FALSE

### The `"guests-can-modify"` property

      "guests-can-modify"        gboolean              : Read / Write

Indicates whether attendees may modify the original event, so that changes are visible to organizers and other attendees. Otherwise, any changes made by attendees will be restricted to that attendee's calendar.

For more information, see the GData specification.

Default value: FALSE

### The `"guests-can-see-guests"` property

      "guests-can-see-guests"    gboolean              : Read / Write

Indicates whether attendees can see other people invited to the event.

For more information, see the GData specification.

Default value: FALSE

### The `"original-event-id"` property

      "original-event-id"        gchar*                : Read

The event ID for the original event, if this event is an exception to a recurring event.

Default value: NULL

Since 0.3.0

### The `"original-event-uri"` property

      "original-event-uri"       gchar*                : Read

The event URI for the original event, if this event is an exception to a recurring event.

Default value: NULL

Since 0.3.0

### The `"recurrence"` property

      "recurrence"               gchar*                : Read / Write

Represents the dates and times when a recurring event takes place. The returned string is in iCal format, as a list of properties.

For more information, see the GData specification.

Default value: NULL

Since 0.3.0

### The `"sequence"` property

      "sequence"                 guint                 : Read / Write

The revision sequence number of the event as defined in Section 4.8.7.4 of RFC 2445.

Default value: 0

### The `"status"` property

      "status"                   gchar*                : Read / Write

The scheduling status of the event. For example: `GDATA_GD_EVENT_STATUS_CANCELED` or `GDATA_GD_EVENT_STATUS_CONFIRMED`.

For more information, see the GData specification.

Default value: NULL

Since 0.2.0

### The `"transparency"` property

      "transparency"             gchar*                : Read / Write

How the event is marked as consuming time on a calendar. For example: `GDATA_GD_EVENT_TRANSPARENCY_OPAQUE` or `GDATA_GD_EVENT_TRANSPARENCY_TRANSPARENT`.

For more information, see the GData specification.

Default value: NULL

### The `"uid"` property

      "uid"                      gchar*                : Read / Write

The globally unique identifier (UID) of the event as defined in Section 4.8.4.7 of RFC 2445.

Default value: NULL

### The `"visibility"` property

      "visibility"               gchar*                : Read / Write

The event's visibility to calendar users. For example: `GDATA_GD_EVENT_VISIBILITY_PUBLIC` or `GDATA_GD_EVENT_VISIBILITY_DEFAULT`.

For more information, see the GData specification.

Default value: NULL