GDataCalendarQuery: GData Reference Manual

GDataCalendarQuery

GDataCalendarQuery — GData Calendar query object

Stability Level

Stable, unless otherwise indicated

Functions

GDataCalendarQuery *	gdata_calendar_query_new ()
GDataCalendarQuery *	gdata_calendar_query_new_with_limits ()
gboolean	gdata_calendar_query_get_future_events ()
void	gdata_calendar_query_set_future_events ()
gboolean	gdata_calendar_query_get_single_events ()
void	gdata_calendar_query_set_single_events ()
const gchar *	gdata_calendar_query_get_order_by ()
void	gdata_calendar_query_set_order_by ()
const gchar *	gdata_calendar_query_get_sort_order ()
void	gdata_calendar_query_set_sort_order ()
gint64	gdata_calendar_query_get_start_min ()
void	gdata_calendar_query_set_start_min ()
gint64	gdata_calendar_query_get_start_max ()
void	gdata_calendar_query_set_start_max ()
gint64	gdata_calendar_query_get_recurrence_expansion_start ()
void	gdata_calendar_query_set_recurrence_expansion_start ()
gint64	gdata_calendar_query_get_recurrence_expansion_end ()
void	gdata_calendar_query_set_recurrence_expansion_end ()
const gchar *	gdata_calendar_query_get_timezone ()
void	gdata_calendar_query_set_timezone ()
guint	gdata_calendar_query_get_max_attendees ()
void	gdata_calendar_query_set_max_attendees ()
gboolean	gdata_calendar_query_show_deleted ()
void	gdata_calendar_query_set_show_deleted ()

Properties

gboolean	future-events	Read / Write
guint	max-attendees	Read / Write
gchar *	order-by	Read / Write
gint64	recurrence-expansion-end	Read / Write
gint64	recurrence-expansion-start	Read / Write
gboolean	show-deleted	Read / Write
gboolean	single-events	Read / Write
gchar *	sort-order	Read / Write
gint64	start-max	Read / Write
gint64	start-min	Read / Write
gchar *	timezone	Read / Write

Types and Values

	GDataCalendarQuery
	GDataCalendarQueryClass

Object Hierarchy

    GObject
    ╰── GDataQuery
        ╰── GDataCalendarQuery

Includes

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

Description

GDataCalendarQuery represents a collection of query parameters specific to the Google Calendar service, which go above and beyond those catered for by GDataQuery.

For more information on the custom GData query parameters supported by GDataCalendarQuery, see the online documentation.

Example 17. Querying for Events

GDataCalendarService *service;
GDataCalendarCalendar *calendar;
GDataCalendarQuery *query;
GDataFeed *feed;
GTimeVal current_time;
GList *i;
GError *error = NULL;

/* Create a service and find a calendar to query in */
service = create_calendar_service ();
calendar = get_calendar (service);

/* Create the query to use. We're going to query for events within the next week which match the search term "party",
 * ordered by last modification time (descending). */
g_get_current_time (&current_time);
query = gdata_calendar_query_new_with_limits ("party", current_time.tv_sec, current_time.tv_sec + 7 * 24 * 60 * 60);
gdata_calendar_query_set_order_by (query, "lastmodified");

/* Execute the query */
feed = gdata_calendar_service_query_events (service, calendar, query, NULL, NULL, NULL, &error);

g_object_unref (query);
g_object_unref (calendar);
g_object_unref (service);

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

/* Iterate through the returned events and do something with them */
for (i = gdata_feed_get_entries (feed); i != NULL; i = i->next) {
    GDataCalendarEvent *event = GDATA_CALENDAR_EVENT (i->data);

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

g_object_unref (feed);

Functions

gdata_calendar_query_new ()

GDataCalendarQuery *
gdata_calendar_query_new (const gchar *q);

Creates a new GDataCalendarQuery with its “q” property set to q .

Parameters

a query string, or NULL.

[allow-none]

Returns

a new GDataCalendarQuery

gdata_calendar_query_new_with_limits ()

GDataCalendarQuery *
gdata_calendar_query_new_with_limits (const gchar *q,
                                      gint64 start_min,
                                      gint64 start_max);

Creates a new GDataCalendarQuery with its “q” property set to q , and the time limits start_min and start_max applied (both in seconds since the UNIX epoch).

Parameters

q	a query string, or `NULL`.	[allow-none]
start_min	a starting time for the event period, or -1
start_max	an ending time for the event period, or -1

Returns

a new GDataCalendarQuery

gdata_calendar_query_get_future_events ()

gboolean
gdata_calendar_query_get_future_events
                               (GDataCalendarQuery *self);

Gets the “future-events” property.

Parameters

self

a GDataCalendarQuery

Returns

the future events property

gdata_calendar_query_set_future_events ()

void
gdata_calendar_query_set_future_events
                               (GDataCalendarQuery *self,
                                gboolean future_events);

Sets the “future-events” property of the GDataCalendarQuery to future_events .

Parameters

self	a GDataCalendarQuery
future_events	`TRUE` to unconditionally show future events, `FALSE` otherwise

gdata_calendar_query_get_single_events ()

gboolean
gdata_calendar_query_get_single_events
                               (GDataCalendarQuery *self);

Gets the “single-events” property.

Parameters

self

a GDataCalendarQuery

Returns

the single events property

gdata_calendar_query_set_single_events ()

void
gdata_calendar_query_set_single_events
                               (GDataCalendarQuery *self,
                                gboolean single_events);

Sets the “single-events” property of the GDataCalendarQuery to single_events .

Parameters

self	a GDataCalendarQuery
single_events	`TRUE` to show recurring events as single events, `FALSE` otherwise

gdata_calendar_query_get_order_by ()

const gchar *
gdata_calendar_query_get_order_by (GDataCalendarQuery *self);

Gets the “order-by” property.

Parameters

self

a GDataCalendarQuery

Returns

the order by property, or NULL if it is unset

gdata_calendar_query_set_order_by ()

void
gdata_calendar_query_set_order_by (GDataCalendarQuery *self,
                                   const gchar *order_by);

Sets the “order-by” property of the GDataCalendarQuery to the new order by string, order_by .

Set order_by to NULL to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
order_by	a new order by string, or `NULL`.	[allow-none]

gdata_calendar_query_get_sort_order ()

const gchar *
gdata_calendar_query_get_sort_order (GDataCalendarQuery *self);

gdata_calendar_query_get_sort_order has been deprecated since version 0.17.7 and should not be used in newly-written code.

Manually sort the results after retrieving them, as this is no longer supported on the server.

Gets the “sort-order” property.

Parameters

self

a GDataCalendarQuery

Returns

the sort order property, or NULL if it is unset

gdata_calendar_query_set_sort_order ()

void
gdata_calendar_query_set_sort_order (GDataCalendarQuery *self,
                                     const gchar *sort_order);

gdata_calendar_query_set_sort_order has been deprecated since version 0.17.7 and should not be used in newly-written code.

Manually sort the results after retrieving them, as this is no longer supported on the server.

Sets the “sort-order” property of the GDataCalendarQuery to the new sort order string, sort_order .

Set sort_order to NULL to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
sort_order	a new sort order string, or `NULL`.	[allow-none]

gdata_calendar_query_get_start_min ()

gint64
gdata_calendar_query_get_start_min (GDataCalendarQuery *self);

Gets the “start-min” property. If the property is unset, -1 will be returned.

Parameters

self

a GDataCalendarQuery

Returns

the UNIX timestamp (in seconds) for the start-min property, or -1

gdata_calendar_query_set_start_min ()

void
gdata_calendar_query_set_start_min (GDataCalendarQuery *self,
                                    gint64 start_min);

Sets the “start-min” property of the GDataCalendarQuery to the new time/date, start_min .

Set start_min to -1 to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
start_min	a new minimum start time (in seconds since the UNIX epoch), or `-1`

gdata_calendar_query_get_start_max ()

gint64
gdata_calendar_query_get_start_max (GDataCalendarQuery *self);

Gets the “start-max” property. If the property is unset, -1 will be returned.

Parameters

self

a GDataCalendarQuery

Returns

the UNIX timestamp (in seconds) for the start-max property, or -1

gdata_calendar_query_set_start_max ()

void
gdata_calendar_query_set_start_max (GDataCalendarQuery *self,
                                    gint64 start_max);

Sets the “start-max” property of the GDataCalendarQuery to the new time/date, start_max .

Set start_max to -1 to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
start_max	a new maximum start time (in seconds since the UNIX epoch), or `-1`

gdata_calendar_query_get_recurrence_expansion_start ()

gint64
gdata_calendar_query_get_recurrence_expansion_start
                               (GDataCalendarQuery *self);

gdata_calendar_query_get_recurrence_expansion_start has been deprecated since version 0.17.7 and should not be used in newly-written code.

Use “single-events” instead, as this is no longer supported on the server.

Gets the “recurrence-expansion-start” property. If the property is unset, -1 will be returned.

Parameters

self

a GDataCalendarQuery

Returns

the UNIX timestamp for the recurrence-expansion-start property, or -1

gdata_calendar_query_set_recurrence_expansion_start ()

void
gdata_calendar_query_set_recurrence_expansion_start
                               (GDataCalendarQuery *self,
                                gint64 start);

gdata_calendar_query_set_recurrence_expansion_start has been deprecated since version 0.17.7 and should not be used in newly-written code.

Use “single-events” instead, as this is no longer supported on the server.

Sets the “recurrence-expansion-start” property of the GDataCalendarQuery to the new time/date, start .

Set start to -1 to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
start	a new start time, or `-1`

gdata_calendar_query_get_recurrence_expansion_end ()

gint64
gdata_calendar_query_get_recurrence_expansion_end
                               (GDataCalendarQuery *self);

gdata_calendar_query_get_recurrence_expansion_end has been deprecated since version 0.17.7 and should not be used in newly-written code.

Use “single-events” instead, as this is no longer supported on the server.

Gets the “recurrence-expansion-end” property. If the property is unset, -1 will be returned.

Parameters

self

a GDataCalendarQuery

Returns

the UNIX timestamp for the recurrence-expansion-end property, or -1

gdata_calendar_query_set_recurrence_expansion_end ()

void
gdata_calendar_query_set_recurrence_expansion_end
                               (GDataCalendarQuery *self,
                                gint64 end);

gdata_calendar_query_set_recurrence_expansion_end has been deprecated since version 0.17.7 and should not be used in newly-written code.

Use “single-events” instead, as this is no longer supported on the server.

Sets the “recurrence-expansion-end” property of the GDataCalendarQuery to the new time/date, end .

Set end to -1 to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
end	a new end time, or `-1`

gdata_calendar_query_get_timezone ()

const gchar *
gdata_calendar_query_get_timezone (GDataCalendarQuery *self);

Gets the “timezone” property.

Parameters

self

a GDataCalendarQuery

Returns

the timezone property, or NULL if it is unset

Since: 0.2.0

gdata_calendar_query_set_timezone ()

void
gdata_calendar_query_set_timezone (GDataCalendarQuery *self,
                                   const gchar *_timezone);

Sets the “timezone” property of the GDataCalendarQuery to the new timezone string, timezone .

Set timezone to NULL to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
_timezone	a new timezone string, or `NULL`.	[allow-none]

Since: 0.2.0

gdata_calendar_query_get_max_attendees ()

guint
gdata_calendar_query_get_max_attendees
                               (GDataCalendarQuery *self);

Gets the “max-attendees” property. If the property is unset, 0 will be returned.

Parameters

self

a GDataCalendarQuery

Returns

the maximum number of attendees, or 0

Since: 0.9.1

gdata_calendar_query_set_max_attendees ()

void
gdata_calendar_query_set_max_attendees
                               (GDataCalendarQuery *self,
                                guint max_attendees);

Sets the “max-attendees” property of the GDataCalendarQuery to the new value, max_attendees .

Set max_attendees to 0 to unset the property in the query URI.

Parameters

self	a GDataCalendarQuery
max_attendees	a new maximum attendee count, or `0`

Since: 0.9.1

gdata_calendar_query_show_deleted ()

gboolean
gdata_calendar_query_show_deleted (GDataCalendarQuery *self);

Gets the “show-deleted” property.

Parameters

self

a GDataCalendarQuery

Returns

TRUE if deleted/cancelled events should be shown, FALSE otherwise

Since: 0.9.1

gdata_calendar_query_set_show_deleted ()

void
gdata_calendar_query_set_show_deleted (GDataCalendarQuery *self,
                                       gboolean show_deleted);

Sets the “show-deleted” property of the GDataCalendarQuery.

Parameters

self	a GDataCalendarQuery
show_deleted	`TRUE` to show deleted events, `FALSE` otherwise

Since: 0.9.1

Types and Values

GDataCalendarQuery

typedef struct _GDataCalendarQuery GDataCalendarQuery;

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

GDataCalendarQueryClass

typedef struct {
} GDataCalendarQueryClass;

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

Property Details

The `“future-events”` property

  “future-events”            gboolean

A shortcut to request all events scheduled for the future. Overrides the “recurrence-expansion-start”, “recurrence-expansion-end”, “start-min” and “start-max” properties.

Flags: Read / Write

Default value: FALSE

The `“max-attendees”` property

  “max-attendees”            guint

Specifies the maximum number of attendees to list for an event. If the actual number of attendees for an event is greater than this value, only the current user and the event organiser are listed.

Flags: Read / Write

Default value: 0

Since: 0.9.1

The `“order-by”` property

  “order-by”                 gchar *

Specifies order of entries in a feed. Supported values are lastmodified and starttime.

Flags: Read / Write

Default value: NULL

The `“recurrence-expansion-end”` property

  “recurrence-expansion-end” gint64

Specifies the end of the time period to expand recurring events for, exclusive.

GDataCalendarQuery:recurrence-expansion-end has been deprecated since version 0.17.7 and should not be used in newly-written code.

Use “single-events” instead, as this is no longer supported on the server.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The `“recurrence-expansion-start”` property

  “recurrence-expansion-start” gint64

Specifies the beginning of the time period to expand recurring events for, inclusive.

GDataCalendarQuery:recurrence-expansion-start has been deprecated since version 0.17.7 and should not be used in newly-written code.

Use “single-events” instead, as this is no longer supported on the server.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The `“show-deleted”` property

  “show-deleted”             gboolean

Whether to include deleted/cancelled events in the query feed. Deleted events have their “status” property set to GDATA_GD_EVENT_STATUS_CANCELED. They do not normally appear in query results.

Flags: Read / Write

Default value: FALSE

Since: 0.9.1

The `“single-events”` property

  “single-events”            gboolean

Indicates whether recurring events should be expanded or represented as a single event.

Flags: Read / Write

Default value: FALSE

The `“sort-order”` property

  “sort-order”               gchar *

Specifies direction of sorting. Supported values are ascending and descending.

By default, results are returned in ascending order.

GDataCalendarQuery:sort-order has been deprecated since version 0.17.7 and should not be used in newly-written code.

Manually sort the results after retrieving them, as this is no longer supported on the server.

Flags: Read / Write

Default value: NULL

The `“start-max”` property

  “start-max”                gint64

Together with “start-min”, creates a timespan such that only events within the timespan are returned

“start-min” is inclusive, while “start-max” is exclusive. Events that overlap the range are included. Both are specified in seconds since the UNIX epoch.

If not specified, the default “start-max” is 2031-01-01.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The `“start-min”` property

  “start-min”                gint64

Together with “start-max”, creates a timespan such that only events within the timespan are returned.

“start-min” is inclusive, while “start-max” is exclusive. Events that overlap the range are included. Both are specified in seconds since the UNIX epoch.

If not specified, the default “start-min” is 1970-01-01.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The `“timezone”` property

  “timezone”                 gchar *

The current timezone. If this is not specified, all times are returned in UTC.

Flags: Read / Write

Default value: NULL

Since: 0.2.0

GDataCalendarQuery

Stability Level

Functions

Properties

Types and Values

Object Hierarchy

Includes

Description

Functions

gdata_calendar_query_new ()

Parameters

Returns

gdata_calendar_query_new_with_limits ()

Parameters

Returns

gdata_calendar_query_get_future_events ()

Parameters

Returns

gdata_calendar_query_set_future_events ()

Parameters

gdata_calendar_query_get_single_events ()

Parameters

Returns

gdata_calendar_query_set_single_events ()

Parameters

gdata_calendar_query_get_order_by ()

Parameters

Returns

gdata_calendar_query_set_order_by ()

Parameters

gdata_calendar_query_get_sort_order ()

Parameters

Returns

gdata_calendar_query_set_sort_order ()

Parameters

gdata_calendar_query_get_start_min ()

Parameters

Returns

gdata_calendar_query_set_start_min ()

Parameters

gdata_calendar_query_get_start_max ()

Parameters

Returns

gdata_calendar_query_set_start_max ()

Parameters

gdata_calendar_query_get_recurrence_expansion_start ()

Parameters

Returns

gdata_calendar_query_set_recurrence_expansion_start ()

Parameters

gdata_calendar_query_get_recurrence_expansion_end ()

Parameters

Returns

gdata_calendar_query_set_recurrence_expansion_end ()

Parameters

gdata_calendar_query_get_timezone ()

Parameters

Returns

gdata_calendar_query_set_timezone ()

Parameters

gdata_calendar_query_get_max_attendees ()

Parameters

Returns

gdata_calendar_query_set_max_attendees ()

Parameters

gdata_calendar_query_show_deleted ()

Parameters

Returns

gdata_calendar_query_set_show_deleted ()

Parameters

Types and Values

GDataCalendarQuery

GDataCalendarQueryClass

Property Details

The “future-events” property

The “max-attendees” property

The “order-by” property

The “recurrence-expansion-end” property

The “recurrence-expansion-start” property

The “show-deleted” property

The `“future-events”` property

The `“max-attendees”` property

The `“order-by”` property

The `“recurrence-expansion-end”` property

The `“recurrence-expansion-start”` property

The `“show-deleted”` property

The `“single-events”` property

The `“sort-order”` property

The `“start-max”` property

The `“start-min”` property

The `“timezone”` property