GDataQuery: GData Reference Manual

## GDataQuery GDataQuery — GData query object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GDataQuery * | gdata_query_new ()
GDataQuery * | gdata_query_new_with_limits ()
gchar * | gdata_query_get_query_uri ()
void | gdata_query_next_page ()
gboolean | gdata_query_previous_page ()
const gchar * | gdata_query_get_q ()
void | gdata_query_set_q ()
const gchar * | gdata_query_get_etag ()
void | gdata_query_set_etag ()
const gchar * | gdata_query_get_author ()
void | gdata_query_set_author ()
const gchar * | gdata_query_get_categories ()
void | gdata_query_set_categories ()
gint64 | gdata_query_get_published_min ()
void | gdata_query_set_published_min ()
gint64 | gdata_query_get_published_max ()
void | gdata_query_set_published_max ()
gint64 | gdata_query_get_updated_min ()
void | gdata_query_set_updated_min ()
gint64 | gdata_query_get_updated_max ()
void | gdata_query_set_updated_max ()
guint | gdata_query_get_start_index ()
void | gdata_query_set_start_index ()
guint | gdata_query_get_max_results ()
void | gdata_query_set_max_results ()
gboolean | gdata_query_is_strict ()
void | gdata_query_set_is_strict ()

## Properties

gchar * | author | Read / Write
gchar * | categories | Read / Write
gchar * | etag | Read / Write
gboolean | is-strict | Read / Write
guint | max-results | Read / Write
gint64 | published-max | Read / Write
gint64 | published-min | Read / Write
gchar * | q | Read / Write
guint | start-index | Read / Write
gint64 | updated-max | Read / Write
gint64 | updated-min | Read / Write

## Types and Values

| GDataQuery
| GDataQueryClass

## Object Hierarchy

        GObject
        ╰── GDataQuery
            ├── GDataCalendarQuery
            ├── GDataContactsQuery
            ├── GDataDocumentsQuery
            ├── GDataFreebaseQuery
            ├── GDataFreebaseSearchQuery
            ├── GDataFreebaseTopicQuery
            ├── GDataPicasaWebQuery
            ├── GDataTasksQuery
            ╰── GDataYouTubeQuery

## Includes

    #include <gdata/gdata-query.h>

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

## Functions

### gdata_query_new ()

    GDataQuery *
    gdata_query_new (const gchar *q);

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

#### Parameters

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

#### Returns

a new GDataQuery

### gdata_query_new_with_limits ()

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

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

#### Parameters

q | a query string, or `NULL`. | [allow-none]
start_index | a one-based start index for the results, or `0` |
max_results | the maximum number of results to return, or `0` |

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

self | a GDataQuery |
q | a new query string, or `NULL`. | [allow-none]

### gdata_query_get_etag ()

    const gchar *
    gdata_query_get_etag (GDataQuery *self);

Gets the “etag” property.

#### Parameters

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.

#### Parameters

self | a GDataQuery |
etag | the new ETag, or `NULL`. | [allow-none]

Since: 0.2.0

### gdata_query_get_author ()

    const gchar *
    gdata_query_get_author (GDataQuery *self);

Gets the “author” property.

#### Parameters

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.

#### Parameters

self | a GDataQuery |
author | the new author string, or `NULL`. | [allow-none]

### gdata_query_get_categories ()

    const gchar *
    gdata_query_get_categories (GDataQuery *self);

Gets the “categories” property.

#### Parameters

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.

#### Parameters

self | a GDataQuery |
categories | the new category string, or `NULL`. | [allow-none]

### gdata_query_get_published_min ()

    gint64
    gdata_query_get_published_min (GDataQuery *self);

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

#### Parameters

self | a GDataQuery |

#### Returns

the published-min property, or `-1`

### gdata_query_set_published_min ()

    void
    gdata_query_set_published_min (GDataQuery *self,
                                   gint64 published_min);

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

Set `published_min` to `-1` to unset the property in the query URI.

#### Parameters

self | a GDataQuery |
published_min | the new minimum publish time, or `-1` |

### gdata_query_get_published_max ()

    gint64
    gdata_query_get_published_max (GDataQuery *self);

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

#### Parameters

self | a GDataQuery |

#### Returns

the published-max property, or `-1`

### gdata_query_set_published_max ()

    void
    gdata_query_set_published_max (GDataQuery *self,
                                   gint64 published_max);

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

Set `published_max` to `-1` to unset the property in the query URI.

#### Parameters

self | a GDataQuery |
published_max | the new maximum publish time, or `-1` |

### gdata_query_get_updated_min ()

    gint64
    gdata_query_get_updated_min (GDataQuery *self);

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

#### Parameters

self | a GDataQuery |

#### Returns

the updated-min property, or `-1`

### gdata_query_set_updated_min ()

    void
    gdata_query_set_updated_min (GDataQuery *self,
                                 gint64 updated_min);

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

Set `updated_min` to `-1` to unset the property in the query URI.

#### Parameters

self | a GDataQuery |
updated_min | the new minimum update time, or `-1` |

### gdata_query_get_updated_max ()

    gint64
    gdata_query_get_updated_max (GDataQuery *self);

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

#### Parameters

self | a GDataQuery |

#### Returns

the updated-max property, or `-1`

### gdata_query_set_updated_max ()

    void
    gdata_query_set_updated_max (GDataQuery *self,
                                 gint64 updated_max);

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

Set `updated_max` to `-1` to unset the property in the query URI.

#### Parameters

self | a GDataQuery |
updated_max | the new maximum update time, or `-1` |

### gdata_query_get_start_index ()

    guint
    gdata_query_get_start_index (GDataQuery *self);

Gets the “start-index” property.

#### Parameters

self | a GDataQuery |

#### Returns

the start index property, or `0` if it is unset

### gdata_query_set_start_index ()

    void
    gdata_query_set_start_index (GDataQuery *self,
                                 guint start_index);

Sets the “start-index” property of the GDataQuery to the new one-based start index, `start_index` .

Set `start_index` to `0` to unset the property in the query URI.

#### Parameters

self | a GDataQuery |
start_index | the new start index, or `0` |

### gdata_query_get_max_results ()

    guint
    gdata_query_get_max_results (GDataQuery *self);

Gets the “max-results” property.

#### Parameters

self | a GDataQuery |

#### Returns

the maximum results property, or `0` if it is unset

### gdata_query_set_max_results ()

    void
    gdata_query_set_max_results (GDataQuery *self,
                                 guint max_results);

Sets the “max-results” property of the GDataQuery to the new maximum results value, `max_results` .

Set `max_results` to `0` to unset the property in the query URI.

#### Parameters

self | a GDataQuery |
max_results | the new maximum results value, or `0` |

### gdata_query_is_strict ()

    gboolean
    gdata_query_is_strict (GDataQuery *self);

Gets the “is-strict” property.

#### Parameters

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

#### Parameters

self | a GDataQuery |
is_strict | the new strict value |

Since: 0.2.0

## Types and Values

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

## Property Details

### The `“author”` property

      “author”                   gchar *

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

Flags: Read / Write

Default value: NULL

### The `“categories”` property

      “categories”               gchar *

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

Flags: Read / Write

Default value: NULL

### The `“etag”` property

      “etag”                     gchar *

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.

Flags: Read / Write

Default value: NULL

Since: 0.2.0

### The `“is-strict”` property

      “is-strict”                gboolean

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

Flags: Read / Write

Default value: FALSE

Since: 0.2.0

### The `“max-results”` property

      “max-results”              guint

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_MAXUINT` for this property.

Use `0` to not specify a maximum number of results.

Flags: Read / Write

Default value: 0

### The `“published-max”` property

      “published-max”            gint64

Upper bound on the entry publish date, exclusive.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“published-min”` property

      “published-min”            gint64

Lower bound on the entry publish date, inclusive.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“q”` property

      “q”                        gchar *

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

Flags: Read / Write

Default value: NULL

### The `“start-index”` property

      “start-index”              guint

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

Use `0` to not specify a start index.

Flags: Read / Write

Default value: 0

### The `“updated-max”` property

      “updated-max”              gint64

Upper bound on the entry update date, exclusive.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“updated-min”` property

      “updated-min”              gint64

Lower bound on the entry update date, inclusive.

Flags: Read / Write

Allowed values: >= -1

Default value: -1