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
char * | 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
char * | sort-order | Read / Write
gint64 | start-max | Read / Write
gint64 | start-min | Read / Write
char * | 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 16. 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
    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

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 (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.

Owner: GDataCalendarQuery

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.

Owner: GDataCalendarQuery

Flags: Read / Write

Default value: 0

Since: 0.9.1

### The `“order-by”` property

      “order-by”                 char *

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

Owner: GDataCalendarQuery

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.

Owner: GDataCalendarQuery

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.

Owner: GDataCalendarQuery

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.

Owner: GDataCalendarQuery

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.

Owner: GDataCalendarQuery

Flags: Read / Write

Default value: FALSE

### The `“sort-order”` property

      “sort-order”               char *

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.

Owner: GDataCalendarQuery

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`.

Owner: GDataCalendarQuery

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`.

Owner: GDataCalendarQuery

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“timezone”` property

      “timezone”                 char *

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

Owner: GDataCalendarQuery

Flags: Read / Write

Default value: NULL

Since: 0.2.0