GDataCalendarQuery

GDataCalendarQuery — GData Calendar query object

Stability Level

Unstable, unless otherwise indicated

Synopsis

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

                    GDataCalendarQuery;
                    GDataCalendarQueryClass;
GDataCalendarQuery * gdata_calendar_query_new           (const gchar *q);
GDataCalendarQuery * gdata_calendar_query_new_with_limits
                                                        (const gchar *q,
                                                         gint64 start_min,
                                                         gint64 start_max);
gboolean            gdata_calendar_query_get_future_events
                                                        (GDataCalendarQuery *self);
void                gdata_calendar_query_set_future_events
                                                        (GDataCalendarQuery *self,
                                                         gboolean future_events);
gboolean            gdata_calendar_query_get_single_events
                                                        (GDataCalendarQuery *self);
void                gdata_calendar_query_set_single_events
                                                        (GDataCalendarQuery *self,
                                                         gboolean single_events);
const gchar *       gdata_calendar_query_get_order_by   (GDataCalendarQuery *self);
void                gdata_calendar_query_set_order_by   (GDataCalendarQuery *self,
                                                         const gchar *order_by);
const gchar *       gdata_calendar_query_get_sort_order (GDataCalendarQuery *self);
void                gdata_calendar_query_set_sort_order (GDataCalendarQuery *self,
                                                         const gchar *sort_order);
gint64              gdata_calendar_query_get_start_min  (GDataCalendarQuery *self);
void                gdata_calendar_query_set_start_min  (GDataCalendarQuery *self,
                                                         gint64 start_min);
gint64              gdata_calendar_query_get_start_max  (GDataCalendarQuery *self);
void                gdata_calendar_query_set_start_max  (GDataCalendarQuery *self,
                                                         gint64 start_max);
gint64              gdata_calendar_query_get_recurrence_expansion_start
                                                        (GDataCalendarQuery *self);
void                gdata_calendar_query_set_recurrence_expansion_start
                                                        (GDataCalendarQuery *self,
                                                         gint64 start);
gint64              gdata_calendar_query_get_recurrence_expansion_end
                                                        (GDataCalendarQuery *self);
void                gdata_calendar_query_set_recurrence_expansion_end
                                                        (GDataCalendarQuery *self,
                                                         gint64 end);
const gchar *       gdata_calendar_query_get_timezone   (GDataCalendarQuery *self);
void                gdata_calendar_query_set_timezone   (GDataCalendarQuery *self,
                                                         const gchar *_timezone);
guint               gdata_calendar_query_get_max_attendees
                                                        (GDataCalendarQuery *self);
void                gdata_calendar_query_set_max_attendees
                                                        (GDataCalendarQuery *self,
                                                         guint max_attendees);
gboolean            gdata_calendar_query_show_deleted   (GDataCalendarQuery *self);
void                gdata_calendar_query_set_show_deleted
                                                        (GDataCalendarQuery *self,
                                                         gboolean show_deleted);

Object Hierarchy

  GObject
   +----GDataQuery
         +----GDataCalendarQuery

Properties

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

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

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
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");
gdata_calendar_query_set_sort_order (query, "descending");

/* 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);


Details

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.


gdata_calendar_query_new ()

GDataCalendarQuery * gdata_calendar_query_new           (const gchar *q);

Creates a new GDataCalendarQuery with its "q" property set to q.

q :

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.

q :

a query string, or NULL. [allow-none]

start_min :

a starting time for the event period, or NULL. [allow-none]

start_max :

an ending time for the event period, or NULL. [allow-none]

Returns :

a new GDataCalendarQuery

gdata_calendar_query_get_future_events ()

gboolean            gdata_calendar_query_get_future_events
                                                        (GDataCalendarQuery *self);

Gets the "future-events" property.

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.

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.

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.

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.

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.

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);

Gets the "sort-order" property.

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);

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.

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.

self :

a GDataCalendarQuery

Returns :

the UNIX timestamp 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.

self :

a GDataCalendarQuery

start_min :

a new minimum start time, 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.

self :

a GDataCalendarQuery

Returns :

the UNIX timestamp 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.

self :

a GDataCalendarQuery

start_max :

a new maximum start time, or -1

gdata_calendar_query_get_recurrence_expansion_start ()

gint64              gdata_calendar_query_get_recurrence_expansion_start
                                                        (GDataCalendarQuery *self);

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

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);

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.

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);

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

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);

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.

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.

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.

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.

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.

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.

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.

self :

a GDataCalendarQuery

show_deleted :

TRUE to show deleted events, FALSE otherwise

Since 0.9.1

Property Details

The "future-events" property

  "future-events"            gboolean              : Read / Write

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

Default value: FALSE


The "max-attendees" property

  "max-attendees"            guint                 : Read / Write

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.

Default value: 0

Since 0.9.1


The "order-by" property

  "order-by"                 gchar*                : Read / Write

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

Default value: NULL


The "recurrence-expansion-end" property

  "recurrence-expansion-end" gint64                : Read / Write

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

Allowed values: >= -1

Default value: -1


The "recurrence-expansion-start" property

  "recurrence-expansion-start" gint64                : Read / Write

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

Allowed values: >= -1

Default value: -1


The "show-deleted" property

  "show-deleted"             gboolean              : Read / Write

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.

Default value: FALSE

Since 0.9.1


The "single-events" property

  "single-events"            gboolean              : Read / Write

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

Default value: FALSE


The "sort-order" property

  "sort-order"               gchar*                : Read / Write

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

Default value: NULL


The "start-max" property

  "start-max"                gint64                : Read / Write

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.

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

Allowed values: >= -1

Default value: -1


The "start-min" property

  "start-min"                gint64                : Read / Write

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.

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

Allowed values: >= -1

Default value: -1


The "timezone" property

  "timezone"                 gchar*                : Read / Write

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

Default value: NULL

Since 0.2.0