GData Reference Manual: GDataYouTubeQuery

## GDataYouTubeQuery GDataYouTubeQuery — GData YouTube query object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataYouTubeQuery;
                        GDataYouTubeQueryClass;
    enum                GDataYouTubeAge;
    enum                GDataYouTubeFormat;
    enum                GDataYouTubeSafeSearch;
    enum                GDataYouTubeSortOrder;
    enum                GDataYouTubeUploader;
    GDataYouTubeQuery * gdata_youtube_query_new             (const gchar *q);
    GDataYouTubeAge     gdata_youtube_query_get_age         (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_age         (GDataYouTubeQuery *self,
                                                             GDataYouTubeAge age);
    GDataYouTubeFormat  gdata_youtube_query_get_format      (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_format      (GDataYouTubeQuery *self,
                                                             GDataYouTubeFormat format);
    const gchar *       gdata_youtube_query_get_language    (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_language    (GDataYouTubeQuery *self,
                                                             const gchar *language);
    const gchar *       gdata_youtube_query_get_license     (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_license     (GDataYouTubeQuery *self,
                                                             const gchar *license);
    void                gdata_youtube_query_get_location    (GDataYouTubeQuery *self,
                                                             gdouble *latitude,
                                                             gdouble *longitude,
                                                             gdouble *radius,
                                                             gboolean *has_location);
    void                gdata_youtube_query_set_location    (GDataYouTubeQuery *self,
                                                             gdouble latitude,
                                                             gdouble longitude,
                                                             gdouble radius,
                                                             gboolean has_location);
    const gchar *       gdata_youtube_query_get_order_by    (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_order_by    (GDataYouTubeQuery *self,
                                                             const gchar *order_by);
    const gchar *       gdata_youtube_query_get_restriction (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_restriction (GDataYouTubeQuery *self,
                                                             const gchar *restriction);
    GDataYouTubeSafeSearch gdata_youtube_query_get_safe_search
                                                            (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_safe_search (GDataYouTubeQuery *self,
                                                             GDataYouTubeSafeSearch safe_search);
    GDataYouTubeSortOrder gdata_youtube_query_get_sort_order
                                                            (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_sort_order  (GDataYouTubeQuery *self,
                                                             GDataYouTubeSortOrder sort_order);
    GDataYouTubeUploader gdata_youtube_query_get_uploader   (GDataYouTubeQuery *self);
    void                gdata_youtube_query_set_uploader    (GDataYouTubeQuery *self,
                                                             GDataYouTubeUploader uploader);

## Object Hierarchy

      GObject
       +----GDataQuery
             +----GDataYouTubeQuery

## Properties

      "age"                      GDataYouTubeAge       : Read / Write
      "format"                   GDataYouTubeFormat    : Read / Write
      "has-location"             gboolean              : Read / Write
      "language"                 gchar*                : Read / Write
      "latitude"                 gdouble               : Read / Write
      "license"                  gchar*                : Read / Write
      "location-radius"          gdouble               : Read / Write
      "longitude"                gdouble               : Read / Write
      "order-by"                 gchar*                : Read / Write
      "restriction"              gchar*                : Read / Write
      "safe-search"              GDataYouTubeSafeSearch  : Read / Write
      "sort-order"               GDataYouTubeSortOrder  : Read / Write
      "uploader"                 GDataYouTubeUploader  : Read / Write

## Description

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

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

## Details

### GDataYouTubeQuery

    typedef struct _GDataYouTubeQuery GDataYouTubeQuery;

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

Since 0.3.0

### GDataYouTubeQueryClass

    typedef struct {
    } GDataYouTubeQueryClass;

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

Since 0.3.0

### enum GDataYouTubeAge

    typedef enum {
    	GDATA_YOUTUBE_AGE_ALL_TIME = 0,
    	GDATA_YOUTUBE_AGE_TODAY,
    	GDATA_YOUTUBE_AGE_THIS_WEEK,
    	GDATA_YOUTUBE_AGE_THIS_MONTH
    } GDataYouTubeAge;

Video ages, allowing queries to be limited to videos uploaded in a recent time period.

`GDATA_YOUTUBE_AGE_ALL_TIME` | retrieve all videos, regardless of the date they were uploaded
`GDATA_YOUTUBE_AGE_TODAY` | retrieve only videos uploaded in the past day
`GDATA_YOUTUBE_AGE_THIS_WEEK` | retrieve only videos uploaded in the past week
`GDATA_YOUTUBE_AGE_THIS_MONTH` | retrieve only videos uploaded in the past month

Since 0.3.0

### enum GDataYouTubeFormat

    typedef enum {
    	GDATA_YOUTUBE_FORMAT_UNKNOWN = 0,
    	GDATA_YOUTUBE_FORMAT_RTSP_H263_AMR = 1,
    	GDATA_YOUTUBE_FORMAT_HTTP_SWF = 5,
    	GDATA_YOUTUBE_FORMAT_RTSP_MPEG4_AAC = 6
    } GDataYouTubeFormat;

Video formats available on YouTube. For more information, see the online documentation.

`GDATA_YOUTUBE_FORMAT_UNKNOWN` | retrieve videos in all formats when querying the service
`GDATA_YOUTUBE_FORMAT_RTSP_H263_AMR` | RTSP streaming URI for mobile video playback; H.263 video (up to 176×144) and AMR audio
`GDATA_YOUTUBE_FORMAT_HTTP_SWF` | HTTP URI to the embeddable player (SWF) for this video
`GDATA_YOUTUBE_FORMAT_RTSP_MPEG4_AAC` | RTSP streaming URI for mobile video playback; MPEG-4 SP video (up to 176×144) and AAC audio

Since 0.3.0

### enum GDataYouTubeSafeSearch

    typedef enum {
    	GDATA_YOUTUBE_SAFE_SEARCH_NONE = 0,
    	GDATA_YOUTUBE_SAFE_SEARCH_MODERATE,
    	GDATA_YOUTUBE_SAFE_SEARCH_STRICT
    } GDataYouTubeSafeSearch;

Safe search levels for removing restricted entries from query results. For more information, see the online documentation.

`GDATA_YOUTUBE_SAFE_SEARCH_NONE` | YouTube will not perform any filtering on the search result set
`GDATA_YOUTUBE_SAFE_SEARCH_MODERATE` | YouTube will filter some content from search results and, at the least, will filter content that is restricted in your locale
`GDATA_YOUTUBE_SAFE_SEARCH_STRICT` | YouTube will try to exclude all restricted content from the search result set

Since 0.3.0

### enum GDataYouTubeSortOrder

    typedef enum {
    	GDATA_YOUTUBE_SORT_NONE = 0,
    	GDATA_YOUTUBE_SORT_ASCENDING,
    	GDATA_YOUTUBE_SORT_DESCENDING
    } GDataYouTubeSortOrder;

Sort orders for the search results from queries. They specify the order of the designated order field.

`GDATA_YOUTUBE_SORT_NONE` | do not explicitly sort in any sense
`GDATA_YOUTUBE_SORT_ASCENDING` | sort results in ascending order of the order field
`GDATA_YOUTUBE_SORT_DESCENDING` | sort results in descending order of the order field

Since 0.3.0

### enum GDataYouTubeUploader

    typedef enum {
    	GDATA_YOUTUBE_UPLOADER_ALL = 0,
    	GDATA_YOUTUBE_UPLOADER_PARTNER
    } GDataYouTubeUploader;

Video uploaders, allowing queries to be limited to returning videos uploaded by YouTube partners.

`GDATA_YOUTUBE_UPLOADER_ALL` | retrieve all videos, regardless of who uploaded them
`GDATA_YOUTUBE_UPLOADER_PARTNER` | retrieve only videos uploaded by YouTube partners

Since 0.3.0

### gdata_youtube_query_new ()

    GDataYouTubeQuery * gdata_youtube_query_new             (const gchar *q);

Creates a new GDataYouTubeQuery with its "q" property set to `q`.

`q` : | a query string, or `NULL`. [allow-none]
Returns : | a new GDataYouTubeQuery

Since 0.3.0

### gdata_youtube_query_get_age ()

    GDataYouTubeAge     gdata_youtube_query_get_age         (GDataYouTubeQuery *self);

Gets the "age" property.

`self` : | a GDataYouTubeQuery
Returns : | the age property

Since 0.3.0

### gdata_youtube_query_set_age ()

    void                gdata_youtube_query_set_age         (GDataYouTubeQuery *self,
                                                             GDataYouTubeAge age);

Sets the "age" property of the GDataYouTubeQuery to `age`.

`self` : | a GDataYouTubeQuery
`age` : | the new age

Since 0.3.0

### gdata_youtube_query_get_format ()

    GDataYouTubeFormat  gdata_youtube_query_get_format      (GDataYouTubeQuery *self);

Gets the "format" property.

`self` : | a GDataYouTubeQuery
Returns : | the format property

Since 0.3.0

### gdata_youtube_query_set_format ()

    void                gdata_youtube_query_set_format      (GDataYouTubeQuery *self,
                                                             GDataYouTubeFormat format);

Sets the "format" property of the GDataYouTubeQuery to `format`.

`self` : | a GDataYouTubeQuery
`format` : | the requested video format

Since 0.3.0

### gdata_youtube_query_get_language ()

    const gchar *       gdata_youtube_query_get_language    (GDataYouTubeQuery *self);

Gets the "language" property.

`self` : | a GDataYouTubeQuery
Returns : | the language property, or `NULL` if it is unset

Since 0.3.0

### gdata_youtube_query_set_language ()

    void                gdata_youtube_query_set_language    (GDataYouTubeQuery *self,
                                                             const gchar *language);

Sets the "language" property of the GDataYouTubeQuery to the new language, `language`.

Set `language` to `NULL` to unset the property in the query URI.

`self` : | a GDataYouTubeQuery
`language` : | a new language name, or `NULL`. [allow-none]

Since 0.3.0

### gdata_youtube_query_get_license ()

    const gchar *       gdata_youtube_query_get_license     (GDataYouTubeQuery *self);

Gets the "license" property.

`self` : | a GDataYouTubeQuery
Returns : | the license property, or `NULL` if it is unset

Since 0.11.0

### gdata_youtube_query_set_license ()

    void                gdata_youtube_query_set_license     (GDataYouTubeQuery *self,
                                                             const gchar *license);

Sets the "license" property of the GDataYouTubeQuery to the new license value, `license`.

Set `license` to `NULL` to unset the property in the query URI.

`self` : | a GDataYouTubeQuery
`license` : | a new license value, or `NULL`. [allow-none]

Since 0.11.0

### gdata_youtube_query_get_location ()

    void                gdata_youtube_query_get_location    (GDataYouTubeQuery *self,
                                                             gdouble *latitude,
                                                             gdouble *longitude,
                                                             gdouble *radius,
                                                             gboolean *has_location);

Gets the location-based properties of the GDataYouTubeQuery: "latitude", "longitude", "location-radius" and "has-location".

`self` : | a GDataYouTubeQuery
`latitude` : | a location in which to return the latitude, or `NULL`. [out caller-allocates][allow-none]
`longitude` : | a location in which to return the longitude, or `NULL`. [out caller-allocates][allow-none]
`radius` : | a location in which to return the location radius, or `NULL`. [out caller-allocates][allow-none]
`has_location` : | a location in which to return `TRUE` if the query is searching for videos with a specific location, `FALSE` otherwise, or `NULL`. [out caller-allocates][allow-none]

Since 0.3.0

### gdata_youtube_query_set_location ()

    void                gdata_youtube_query_set_location    (GDataYouTubeQuery *self,
                                                             gdouble latitude,
                                                             gdouble longitude,
                                                             gdouble radius,
                                                             gboolean has_location);

Sets the location-based properties of the GDataYouTubeQuery: "latitude", "longitude", "location-radius" and "has-location".

`self` : | a GDataYouTubeQuery
`latitude` : | the new latitude, or `G_MAXDOUBLE`
`longitude` : | the new longitude, or `G_MAXDOUBLE`
`radius` : | the new location radius, or `0`
`has_location` : | `TRUE` if the query is for videos with a specific location, `FALSE` otherwise

Since 0.3.0

### gdata_youtube_query_get_order_by ()

    const gchar *       gdata_youtube_query_get_order_by    (GDataYouTubeQuery *self);

Gets the "order-by" property.

`self` : | a GDataYouTubeQuery
Returns : | the order by property, or `NULL` if it is unset

Since 0.3.0

### gdata_youtube_query_set_order_by ()

    void                gdata_youtube_query_set_order_by    (GDataYouTubeQuery *self,
                                                             const gchar *order_by);

Sets the "order-by" property of the GDataYouTubeQuery to the new order by string, `order_by`.

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

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

Since 0.3.0

### gdata_youtube_query_get_restriction ()

    const gchar *       gdata_youtube_query_get_restriction (GDataYouTubeQuery *self);

Gets the "restriction" property.

`self` : | a GDataYouTubeQuery
Returns : | the restriction property, or `NULL` if it is unset

Since 0.3.0

### gdata_youtube_query_set_restriction ()

    void                gdata_youtube_query_set_restriction (GDataYouTubeQuery *self,
                                                             const gchar *restriction);

Sets the "restriction" property of the GDataYouTubeQuery to the new restriction string, `restriction`.

Set `restriction` to `NULL` to unset the property in the query URI.

`self` : | a GDataYouTubeQuery
`restriction` : | a new restriction string, or `NULL`. [allow-none]

Since 0.3.0

### gdata_youtube_query_get_safe_search ()

    GDataYouTubeSafeSearch gdata_youtube_query_get_safe_search
                                                            (GDataYouTubeQuery *self);

Gets the "safe-search" property.

`self` : | a GDataYouTubeQuery
Returns : | the safe search property

Since 0.3.0

### gdata_youtube_query_set_safe_search ()

    void                gdata_youtube_query_set_safe_search (GDataYouTubeQuery *self,
                                                             GDataYouTubeSafeSearch safe_search);

Sets the "safe-search" property of the GDataYouTubeQuery to `safe_search`.

`self` : | a GDataYouTubeQuery
`safe_search` : | a new safe search level

Since 0.3.0

### gdata_youtube_query_get_sort_order ()

    GDataYouTubeSortOrder gdata_youtube_query_get_sort_order
                                                            (GDataYouTubeQuery *self);

Gets the "sort-order" property.

`self` : | a GDataYouTubeQuery
Returns : | the sort order property

Since 0.3.0

### gdata_youtube_query_set_sort_order ()

    void                gdata_youtube_query_set_sort_order  (GDataYouTubeQuery *self,
                                                             GDataYouTubeSortOrder sort_order);

Sets the "sort-order" property of the GDataYouTubeQuery to `sort_order`.

Set `sort_order` to `GDATA_YOUTUBE_SORT_NONE` to unset the property in the query URI.

`self` : | a GDataYouTubeQuery
`sort_order` : | the new sort order

Since 0.3.0

### gdata_youtube_query_get_uploader ()

    GDataYouTubeUploader gdata_youtube_query_get_uploader   (GDataYouTubeQuery *self);

Gets the "uploader" property.

`self` : | a GDataYouTubeQuery
Returns : | the uploader property

Since 0.3.0

### gdata_youtube_query_set_uploader ()

    void                gdata_youtube_query_set_uploader    (GDataYouTubeQuery *self,
                                                             GDataYouTubeUploader uploader);

Sets the "uploader" property of the GDataYouTubeQuery to `uploader`.

`self` : | a GDataYouTubeQuery
`uploader` : | the new uploader

Since 0.3.0

## Property Details

### The `"age"` property

      "age"                      GDataYouTubeAge       : Read / Write

Restricts the search to videos uploaded within the specified time period. To retrieve videos irrespective of their age, set the property to `GDATA_YOUTUBE_AGE_ALL_TIME`.

Default value: GDATA_YOUTUBE_AGE_ALL_TIME

Since 0.3.0

### The `"format"` property

      "format"                   GDataYouTubeFormat    : Read / Write

Specifies that videos must be available in a particular video format. Use `GDATA_YOUTUBE_FORMAT_UNKNOWN` to retrieve videos irrespective of their format availability.

Default value: GDATA_YOUTUBE_FORMAT_UNKNOWN

Since 0.3.0

### The `"has-location"` property

      "has-location"             gboolean              : Read / Write

Whether to restrict search results to videos with specific coordinates associated with them. If used with a given "latitude" and "longitude", only videos with specific coordinates (not those with merely a descriptive address) will be returned. If used without a latitude and longitude set, only videos with specific coordinates (regardless of those coordinates) will be returned.

For more information, see the documentation for "latitude".

Default value: FALSE

Since 0.3.0

### The `"language"` property

      "language"                 gchar*                : Read / Write

Restricts the search to videos that have a title, description or keywords in a specified language. The language code should be a two-letter ISO 639-1 code; or you can use `zh-Hans` for simplified Chinese and `zh-Hant` for traditional Chinese.

For more information, see the online documentation.

Default value: NULL

Since 0.3.0

### The `"latitude"` property

      "latitude"                 gdouble               : Read / Write

The latitude of a particular location of which videos should be found. This should be used in conjunction with "longitude"; if either property is outside the valid range, neither will be used. Valid latitudes are between `-90` and `90`0 degrees; any values of this property outside that range will unset the property in the query URI.

If "location-radius" is a non-`0` value, this will define a circle from which videos should be found.

If "has-location" is `TRUE`, only videos which are associated with specific coordinates in the search circle will be returned. Otherwise, videos which have a relevant descriptive address (but no specific coordinates) will also be returned.

For more information, see the online documentation.

Default value: 0

Since 0.3.0

### The `"license"` property

      "license"                  gchar*                : Read / Write

The content license which should be used to filter search results. If set to, for example, `GDATA_YOUTUBE_LICENSE_CC`, only videos which are Creative Commons licensed will be returned in search results. Set this to `NULL` to return videos under any license.

For more information, see the online documentation.

Default value: NULL

Since 0.11.0

### The `"location-radius"` property

      "location-radius"          gdouble               : Read / Write

The radius, in metres, of a circle from within which videos should be returned. The circle is centred on the latitude and longitude given in "latitude" and "longitude".

Set this property to `0` to search for specific coordinates, rather than within a given radius.

For more information, see the documentation for "latitude".

Allowed values: >= 0

Default value: 0

Since 0.3.0

### The `"longitude"` property

      "longitude"                gdouble               : Read / Write

The longitude of a particular location of which videos should be found. This should be used in conjunction with "latitude"; if either property is outside the valid range, neither will be used. Valid longitudes are between `-180` and `180` degrees; any values of this property outside that range will unset the property in the query URI.

For more information, see the documentation for "latitude".

Default value: 0

Since 0.3.0

### The `"order-by"` property

      "order-by"                 gchar*                : Read / Write

Specifies the order of entries in a feed. Supported values are `relevance`, `published`, `viewCount` and `rating`.

Additionally, results most relevant to a specific language can be returned by setting the property to `relevance_lang_`languageCode``, where `languageCode` is an ISO 639-1 language code, as used in "language".

For more information, see the online documentation.

Default value: NULL

Since 0.3.0

### The `"restriction"` property

      "restriction"              gchar*                : Read / Write

The IP address that should be used to filter videos playable only in specific countries. This should be the IP address of the client, if different to the IP address in use by the library. Alternatively, it can be an ISO 3166 two-letter country code.

For more information, see the online documentation.

Default value: NULL

Since 0.3.0

### The `"safe-search"` property

      "safe-search"              GDataYouTubeSafeSearch  : Read / Write

Whether the search results should include restricted content as well as standard content.

For more information, see the online documentation.

Default value: GDATA_YOUTUBE_SAFE_SEARCH_MODERATE

Since 0.3.0

### The `"sort-order"` property

      "sort-order"               GDataYouTubeSortOrder  : Read / Write

Specifies the direction of sorting. To use the default sort order, set the property to `GDATA_YOUTUBE_SORT_NONE`.

Default value: GDATA_YOUTUBE_SORT_NONE

Since 0.3.0

### The `"uploader"` property

      "uploader"                 GDataYouTubeUploader  : Read / Write

Restricts the search to videos from the specified type of uploader. Currently, this can only be used to restrict searches to videos from YouTube partners.

Default value: GDATA_YOUTUBE_UPLOADER_ALL

Since 0.3.0