GDataQuery

GDataQuery — GData query object

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <gdata/gdata-query.h>

                    GDataQuery;
                    GDataQueryClass;
GDataQuery *        gdata_query_new                     (const gchar *q);
GDataQuery *        gdata_query_new_with_limits         (const gchar *q,
                                                         gint start_index,
                                                         gint max_results);
GDataQuery *        gdata_query_new_for_id              (const gchar *entry_id);
gchar *             gdata_query_get_query_uri           (GDataQuery *self,
                                                         const gchar *feed_uri);
void                gdata_query_next_page               (GDataQuery *self);
gboolean            gdata_query_previous_page           (GDataQuery *self);
const gchar *       gdata_query_get_q                   (GDataQuery *self);
void                gdata_query_set_q                   (GDataQuery *self,
                                                         const gchar *q);
const gchar *       gdata_query_get_entry_id            (GDataQuery *self);
void                gdata_query_set_entry_id            (GDataQuery *self,
                                                         const gchar *entry_id);
const gchar *       gdata_query_get_etag                (GDataQuery *self);
void                gdata_query_set_etag                (GDataQuery *self,
                                                         const gchar *etag);
const gchar *       gdata_query_get_author              (GDataQuery *self);
void                gdata_query_set_author              (GDataQuery *self,
                                                         const gchar *author);
const gchar *       gdata_query_get_categories          (GDataQuery *self);
void                gdata_query_set_categories          (GDataQuery *self,
                                                         const gchar *categories);
void                gdata_query_get_published_min       (GDataQuery *self,
                                                         GTimeVal *published_min);
void                gdata_query_set_published_min       (GDataQuery *self,
                                                         GTimeVal *published_min);
void                gdata_query_get_published_max       (GDataQuery *self,
                                                         GTimeVal *published_max);
void                gdata_query_set_published_max       (GDataQuery *self,
                                                         GTimeVal *published_max);
void                gdata_query_get_updated_min         (GDataQuery *self,
                                                         GTimeVal *updated_min);
void                gdata_query_set_updated_min         (GDataQuery *self,
                                                         GTimeVal *updated_min);
void                gdata_query_get_updated_max         (GDataQuery *self,
                                                         GTimeVal *updated_max);
void                gdata_query_set_updated_max         (GDataQuery *self,
                                                         GTimeVal *updated_max);
gint                gdata_query_get_start_index         (GDataQuery *self);
void                gdata_query_set_start_index         (GDataQuery *self,
                                                         gint start_index);
gint                gdata_query_get_max_results         (GDataQuery *self);
void                gdata_query_set_max_results         (GDataQuery *self,
                                                         gint max_results);
gboolean            gdata_query_is_strict               (GDataQuery *self);
void                gdata_query_set_is_strict           (GDataQuery *self,
                                                         gboolean is_strict);

Object Hierarchy

  GObject
   +----GDataQuery
         +----GDataCalendarQuery
         +----GDataContactsQuery
         +----GDataDocumentsQuery
         +----GDataPicasaWebQuery
         +----GDataYouTubeQuery

Properties

  "author"                   gchar*                : Read / Write
  "categories"               gchar*                : Read / Write
  "entry-id"                 gchar*                : Read / Write
  "etag"                     gchar*                : Read / Write
  "is-strict"                gboolean              : Read / Write
  "max-results"              gint                  : Read / Write
  "published-max"            GTimeVal*             : Read / Write
  "published-min"            GTimeVal*             : Read / Write
  "q"                        gchar*                : Read / Write
  "start-index"              gint                  : Read / Write
  "updated-max"              GTimeVal*             : Read / Write
  "updated-min"              GTimeVal*             : Read / Write

Description

GDataQuery represents a collection of query parameters used in a series of queries on a GDataService. It allows the query parameters to be set, with the aim of building a query URI using gdata_query_get_query_uri(). Pagination is supported using gdata_query_next_page() and gdata_query_previous_page().

Each query can have an ETag associated with it, which is a unique identifier for the set of query results produced by the query. Each time a query is made, gdata_service_query() will set the "etag" property of the accompanying query to a value returned by the server. If the same query is made again (using the same GDataQuery instance), the server can skip returning the resulting GDataFeed if its contents haven't changed (in this case, gdata_service_query() will return NULL with an empty error).

For this reason, code using GDataQuery should be careful when reusing GDataQuery instances: the code should either unset "etag" after every query or (preferably) gracefully handle the case where gdata_service_query() returns NULL to signify unchanged results.

Every time a property of a GDataQuery instance is changed, the instance's ETag will be unset.

For more information on the standard GData query parameters supported by GDataQuery, see the online documentation.

Details

GDataQuery

typedef struct _GDataQuery GDataQuery;

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


GDataQueryClass

typedef struct {
} GDataQueryClass;

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


gdata_query_new ()

GDataQuery *        gdata_query_new                     (const gchar *q);

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

q :

a query string

Returns :

a new GDataQuery

gdata_query_new_with_limits ()

GDataQuery *        gdata_query_new_with_limits         (const gchar *q,
                                                         gint start_index,
                                                         gint max_results);

Creates a new GDataQuery with its "q" property set to q, and the limits start_index and max_results applied.

q :

a query string

start_index :

a one-based start index for the results

max_results :

the maximum number of results to return

Returns :

a new GDataQuery

gdata_query_new_for_id ()

GDataQuery *        gdata_query_new_for_id              (const gchar *entry_id);

Creates a new GDataQuery to query for entry_id.

entry_id :

an entry URN ID

Returns :

a new GDataQuery

gdata_query_get_query_uri ()

gchar *             gdata_query_get_query_uri           (GDataQuery *self,
                                                         const gchar *feed_uri);

Builds a query URI from the given base feed URI, using the properties of the GDataQuery. This function will take care of all necessary URI escaping, so it should not be done beforehand.

The query URI is what functions like gdata_service_query() use to query the online service.

self :

a GDataQuery

feed_uri :

the feed URI on which to build the query URI

Returns :

a query URI; free with g_free()

gdata_query_next_page ()

void                gdata_query_next_page               (GDataQuery *self);

Changes the state of the GDataQuery such that when gdata_query_get_query_uri() is next called, it will build the query URI for the next page in the result set.

Ideally, the URI of the next page is retrieved from a feed automatically when gdata_service_query() is called, but gdata_query_next_page() will fall back to using "start-index" to emulate true pagination if this fails.

You should not implement pagination manually using "start-index".

self :

a GDataQuery

gdata_query_previous_page ()

gboolean            gdata_query_previous_page           (GDataQuery *self);

Changes the state of the GDataQuery such that when gdata_query_get_query_uri() is next called, it will build the query URI for the previous page in the result set.

See the documentation for gdata_query_next_page() for an explanation of how query URIs from the feeds are used to this end.

self :

a GDataQuery

Returns :

TRUE if there is a previous page and it has been switched to, FALSE otherwise

gdata_query_get_q ()

const gchar *       gdata_query_get_q                   (GDataQuery *self);

Gets the "q" property.

self :

a GDataQuery

Returns :

the q property, or NULL if it is unset

gdata_query_set_q ()

void                gdata_query_set_q                   (GDataQuery *self,
                                                         const gchar *q);

Sets the "q" property of the GDataQuery to the new query string, q.

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

self :

a GDataQuery

q :

a new query string, or NULL

gdata_query_get_entry_id ()

const gchar *       gdata_query_get_entry_id            (GDataQuery *self);

Gets the "entry-id" property.

self :

a GDataQuery

Returns :

the entry ID property, or NULL if it is unset

gdata_query_set_entry_id ()

void                gdata_query_set_entry_id            (GDataQuery *self,
                                                         const gchar *entry_id);

Sets the "entry-id" property of the GDataQuery to the new entry ID string, entry_id.

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

self :

a GDataQuery

entry_id :

the new entry ID string

gdata_query_get_etag ()

const gchar *       gdata_query_get_etag                (GDataQuery *self);

Gets the "etag" property.

self :

a GDataQuery

Returns :

the ETag property, or NULL if it is unset

Since 0.2.0


gdata_query_set_etag ()

void                gdata_query_set_etag                (GDataQuery *self,
                                                         const gchar *etag);

Sets the "etag" property of the GDataQuery to the new ETag, etag.

Set etag to NULL to not check against the server-side ETag.

self :

a GDataQuery

etag :

the new ETag

Since 0.2.0


gdata_query_get_author ()

const gchar *       gdata_query_get_author              (GDataQuery *self);

Gets the "author" property.

self :

a GDataQuery

Returns :

the author property, or NULL if it is unset

gdata_query_set_author ()

void                gdata_query_set_author              (GDataQuery *self,
                                                         const gchar *author);

Sets the "author" property of the GDataQuery to the new author string, author.

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

self :

a GDataQuery

author :

the new author string, or NULL

gdata_query_get_categories ()

const gchar *       gdata_query_get_categories          (GDataQuery *self);

Gets the "categories" property.

self :

a GDataQuery

Returns :

the categories property, or NULL if it is unset

gdata_query_set_categories ()

void                gdata_query_set_categories          (GDataQuery *self,
                                                         const gchar *categories);

Sets the "categories" property of the GDataQuery to the new category string, categories.

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

self :

a GDataQuery

categories :

the new category string, or NULL

gdata_query_get_published_min ()

void                gdata_query_get_published_min       (GDataQuery *self,
                                                         GTimeVal *published_min);

Gets the "published-min" property and puts it in published_min. If the property is unset, both fields in the GTimeVal will be set to 0.

self :

a GDataQuery

published_min :

a GTimeVal

gdata_query_set_published_min ()

void                gdata_query_set_published_min       (GDataQuery *self,
                                                         GTimeVal *published_min);

Sets the "published-min" property of the GDataQuery to the new minimum publish time, published_min.

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

self :

a GDataQuery

published_min :

the new minimum publish time, or NULL

gdata_query_get_published_max ()

void                gdata_query_get_published_max       (GDataQuery *self,
                                                         GTimeVal *published_max);

Gets the "published-max" property and puts it in published_max. If the property is unset, both fields in the GTimeVal will be set to 0.

self :

a GDataQuery

published_max :

a GTimeVal

gdata_query_set_published_max ()

void                gdata_query_set_published_max       (GDataQuery *self,
                                                         GTimeVal *published_max);

Sets the "published-max" property of the GDataQuery to the new maximum publish time, published_max.

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

self :

a GDataQuery

published_max :

the new maximum publish time, or NULL

gdata_query_get_updated_min ()

void                gdata_query_get_updated_min         (GDataQuery *self,
                                                         GTimeVal *updated_min);

Gets the "updated-min" property and puts it in updated_min. If the property is unset, both fields in the GTimeVal will be set to 0.

self :

a GDataQuery

updated_min :

a GTimeVal

gdata_query_set_updated_min ()

void                gdata_query_set_updated_min         (GDataQuery *self,
                                                         GTimeVal *updated_min);

Sets the "updated-min" property of the GDataQuery to the new minimum update time, updated_min.

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

self :

a GDataQuery

updated_min :

the new minimum update time, or NULL

gdata_query_get_updated_max ()

void                gdata_query_get_updated_max         (GDataQuery *self,
                                                         GTimeVal *updated_max);

Gets the "updated-max" property and puts it in updated_max. If the property is unset, both fields in the GTimeVal will be set to 0.

self :

a GDataQuery

updated_max :

a GTimeVal

gdata_query_set_updated_max ()

void                gdata_query_set_updated_max         (GDataQuery *self,
                                                         GTimeVal *updated_max);

Sets the "updated-max" property of the GDataQuery to the new maximum update time, updated_max.

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

self :

a GDataQuery

updated_max :

the new maximum update time, or NULL

gdata_query_get_start_index ()

gint                gdata_query_get_start_index         (GDataQuery *self);

Gets the "start-index" property.

self :

a GDataQuery

Returns :

the start index property, or -1 if it is unset

gdata_query_set_start_index ()

void                gdata_query_set_start_index         (GDataQuery *self,
                                                         gint start_index);

Sets the "start-index" property of the GDataQuery to the new one-based start index, start_index.

Set start_index to -1 or 0 to unset the property in the query URI.

self :

a GDataQuery

start_index :

the new start index

gdata_query_get_max_results ()

gint                gdata_query_get_max_results         (GDataQuery *self);

Gets the "max-results" property.

self :

a GDataQuery

Returns :

the maximum results property, or -1 if it is unset

gdata_query_set_max_results ()

void                gdata_query_set_max_results         (GDataQuery *self,
                                                         gint max_results);

Sets the "max-results" property of the GDataQuery to the new maximum results value, max_results.

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

self :

a GDataQuery

max_results :

the new maximum results value

gdata_query_is_strict ()

gboolean            gdata_query_is_strict               (GDataQuery *self);

Gets the "is-strict" property.

self :

a GDataQuery

Returns :

the strict property

Since 0.2.0


gdata_query_set_is_strict ()

void                gdata_query_set_is_strict           (GDataQuery *self,
                                                         gboolean is_strict);

Sets the "is-strict" property of the GDataQuery to the new strict value, is_strict.

self :

a GDataQuery

is_strict :

the new strict value

Since 0.2.0

Property Details

The "author" property

  "author"                   gchar*                : Read / Write

An entry author. The service returns entries where the author name and/or e-mail address match your query string.

Default value: NULL


The "categories" property

  "categories"               gchar*                : Read / Write

A category filter.

You can query on multiple categories by listing multiple categories separated by slashes. The service returns all entries that match all of the categories (like using AND between terms). For example: Fritz/Laurie returns entries that match both categories ("Fritz" and "Laurie").

To do an OR between terms, use a pipe character (|). For example: Fritz%7CLaurie returns entries that match either category.

An entry matches a specified category if the entry is in a category that has a matching term or label, as defined in the Atom specification. (Roughly, the "term" is the internal string used by the software to identify the category, while the "label" is the human-readable string presented to a user in a user interface.)

To exclude entries that match a given category, use the form -categoryname.

To query for a category that has a scheme – such as <category scheme="urn:google.com" term="public"/> – you must place the scheme in curly braces before the category name. For example: {urn:google.com}public. To match a category that has no scheme, use an empty pair of curly braces. If you don't specify curly braces, then categories in any scheme will match.

The above features can be combined. For example: A|-{urn:google.com}B/-C means (A OR (NOT B)) AND (NOT C).

Default value: NULL


The "entry-id" property

  "entry-id"                 gchar*                : Read / Write

The ID of a specific entry to be retrieved. If you specify an entry ID, you cannot specify any other parameters.

Default value: NULL


The "etag" property

  "etag"                     gchar*                : Read / Write

The ETag against which to check for updates. If the server-side ETag matches this one, the requested feed hasn't changed, and is not returned unnecessarily.

Setting any of the other query properties will unset the ETag, as ETags match against entire queries. If the ETag should be used in a query, it must be set again using gdata_query_set_etag() after setting any other properties.

Default value: NULL

Since 0.2.0


The "is-strict" property

  "is-strict"                gboolean              : Read / Write

Strict query parameter checking. If this is enabled, an error will be returned by the online service if a parameter is not recognised.

Default value: FALSE

Since 0.2.0


The "max-results" property

  "max-results"              gint                  : Read / Write

Maximum number of results to be retrieved. Most services have a default "max-results" size imposed by the server; if you wish to receive the entire feed, specify a large number such as G_MAXINT for this property.

Allowed values: >= G_MAXULONG

Default value: -1


The "published-max" property

  "published-max"            GTimeVal*             : Read / Write

Upper bound on the entry publish date, exclusive.


The "published-min" property

  "published-min"            GTimeVal*             : Read / Write

Lower bound on the entry publish date, inclusive.


The "q" property

  "q"                        gchar*                : Read / Write

A full-text query string.

When creating a query, list search terms separated by spaces, in the form term1 term2 term3. (As with all of the query parameter values, the spaces must be URL encoded.) The service returns all entries that match all of the search terms (like using AND between terms). Like Google's web search, a service searches on complete words (and related words with the same stem), not substrings.

To search for an exact phrase, enclose the phrase in quotation marks: "exact phrase".

To exclude entries that match a given term, use the form -term.

The search is case-insensitive.

Example: to search for all entries that contain the exact phrase "Elizabeth Bennet" and the word "Darcy" but don't contain the word "Austen", use the following query: "Elizabeth Bennet" Darcy -Austen.

Default value: NULL


The "start-index" property

  "start-index"              gint                  : Read / Write

The one-based index of the first result to be retrieved. Use gdata_query_next_page() and gdata_query_previous_page() to implement pagination, rather than manually changing "start-index".

Allowed values: >= G_MAXULONG

Default value: -1


The "updated-max" property

  "updated-max"              GTimeVal*             : Read / Write

Upper bound on the entry update date, exclusive.


The "updated-min" property

  "updated-min"              GTimeVal*             : Read / Write

Lower bound on the entry update date, inclusive.