GDataYouTubeVideo

## GDataYouTubeVideo GDataYouTubeVideo — GData YouTube video object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataYouTubeVideo;
                        GDataYouTubeVideoClass;
    enum                GDataYouTubeAspectRatio;
    GDataYouTubeVideo * gdata_youtube_video_new             (const gchar *id);
    GDataYouTubeContent * gdata_youtube_video_look_up_content
                                                            (GDataYouTubeVideo *self,
                                                             const gchar *type);
    GList *             gdata_youtube_video_get_thumbnails  (GDataYouTubeVideo *self);
    GDataMediaCategory * gdata_youtube_video_get_category   (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_category    (GDataYouTubeVideo *self,
                                                             GDataMediaCategory *category);
    GDataYouTubeCredit * gdata_youtube_video_get_credit     (GDataYouTubeVideo *self);
    const gchar *       gdata_youtube_video_get_description (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_description (GDataYouTubeVideo *self,
                                                             const gchar *description);
    guint               gdata_youtube_video_get_duration    (GDataYouTubeVideo *self);
    const gchar *       gdata_youtube_video_get_keywords    (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_keywords    (GDataYouTubeVideo *self,
                                                             const gchar *keywords);
    const gchar *       gdata_youtube_video_get_location    (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_location    (GDataYouTubeVideo *self,
                                                             const gchar *location);
    guint               gdata_youtube_video_get_view_count  (GDataYouTubeVideo *self);
    guint               gdata_youtube_video_get_favorite_count
                                                            (GDataYouTubeVideo *self);
    gboolean            gdata_youtube_video_is_restricted_in_country
                                                            (GDataYouTubeVideo *self,
                                                             const gchar *country);
    gboolean            gdata_youtube_video_get_no_embed    (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_no_embed    (GDataYouTubeVideo *self,
                                                             gboolean no_embed);
    const gchar *       gdata_youtube_video_get_player_uri  (GDataYouTubeVideo *self);
    gboolean            gdata_youtube_video_is_private      (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_is_private  (GDataYouTubeVideo *self,
                                                             gboolean is_private);
    gboolean            gdata_youtube_video_is_draft        (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_is_draft    (GDataYouTubeVideo *self,
                                                             gboolean is_draft);
    GDataYouTubeState * gdata_youtube_video_get_state       (GDataYouTubeVideo *self);
    void                gdata_youtube_video_get_rating      (GDataYouTubeVideo *self,
                                                             guint *min,
                                                             guint *max,
                                                             guint *count,
                                                             gdouble *average);
    void                gdata_youtube_video_get_uploaded    (GDataYouTubeVideo *self,
                                                             GTimeVal *uploaded);
    void                gdata_youtube_video_get_recorded    (GDataYouTubeVideo *self,
                                                             GTimeVal *recorded);
    void                gdata_youtube_video_set_recorded    (GDataYouTubeVideo *self,
                                                             GTimeVal *recorded);
    const gchar *       gdata_youtube_video_get_video_id    (GDataYouTubeVideo *self);
    gchar *             gdata_youtube_video_get_video_id_from_uri
                                                            (const gchar *video_uri);
    GDataYouTubeAspectRatio  gdata_youtube_video_get_aspect_ratio
                                                            (GDataYouTubeVideo *self);
    void                gdata_youtube_video_set_aspect_ratio
                                                            (GDataYouTubeVideo *self,
                                                             GDataYouTubeAspectRatio aspect_ratio);

## Object Hierarchy

      GObject
       +----GDataParsable
             +----GDataEntry
                   +----GDataYouTubeVideo

## Properties

      "aspect-ratio"             GDataYouTubeAspectRatio  : Read / Write
      "average-rating"           gdouble               : Read
      "category"                 GDataMediaCategory*   : Read / Write
      "credit"                   GDataYouTubeCredit*   : Read
      "description"              gchar*                : Read / Write
      "duration"                 guint                 : Read
      "favorite-count"           guint                 : Read
      "is-draft"                 gboolean              : Read / Write
      "is-private"               gboolean              : Read / Write
      "keywords"                 gchar*                : Read / Write
      "location"                 gchar*                : Read / Write
      "max-rating"               guint                 : Read
      "min-rating"               guint                 : Read
      "no-embed"                 gboolean              : Read / Write
      "player-uri"               gchar*                : Read
      "rating-count"             guint                 : Read
      "recorded"                 GDataTimeVal*         : Read / Write
      "state"                    GDataYouTubeState*    : Read
      "uploaded"                 GDataTimeVal*         : Read
      "video-id"                 gchar*                : Read
      "view-count"               guint                 : Read

## Description

GDataYouTubeVideo is a subclass of GDataEntry to represent a single video on YouTube, either when uploading or querying.

For more details of YouTube's GData API, see the online documentation.

Example 1. Getting Basic Video Data

    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
    GDataYouTubeVideo *video;
    const gchar *video_id, *title, *player_uri, *description, *video_uri = NULL;
    GTimeVal updated, published;
    GDataMediaContent *content;
    GList *thumbnails;

    video = gdata_youtube_service_query_single_video (service, NULL, "R-9gzmQHoe0", NULL, NULL);

    video_id = gdata_youtube_video_get_video_id (video); /* e.g. "R-9gzmQHoe0" */
    title = gdata_entry_get_title (GDATA_ENTRY (video)); /* e.g. "Korpiklaani Vodka (official video 2009)" */
    player_uri = gdata_youtube_video_get_player_uri (video); /* e.g. "http://www.youtube.com/watch?v=ZTUVgYoeN_b" */
    description = gdata_youtube_video_get_description (video); /* e.g. "Vodka is the first single from the album..." */
    gdata_entry_get_published (GDATA_ENTRY (video), &published); /* Date and time the video was originally published */
    gdata_entry_get_updated (GDATA_ENTRY (video), &updated); /* When the video was most recently updated by the author */

    /* Retrieve a specific encoding of the video in <a class="link" href="GDataMediaContent.html" title="GDataMediaContent">GDataMediaContent</a> format */
    content = gdata_youtube_video_look_up_content (video, "video/3gpp");
    if (content != NULL)
        video_uri = gdata_media_content_get_uri (content); /* the URI for the direct 3GP version of the video */
    else
        /* Fall back and try a different video encoding? SWF ("application/x-shockwave-flash") is always present. */

    /* Get a list of <a class="link" href="GDataMediaThumbnail.html" title="GDataMediaThumbnail">GDataMediaThumbnail</a>s for the video */
    for (thumbnails = gdata_youtube_video_get_thumbnails (video); thumbnails != NULL; thumbnails = thumbnails->next)
        download_and_do_something_with_thumbnail (gdata_media_thumbnail_get_uri (thumbnail));

    g_object_unref (video);

## Details

### GDataYouTubeVideo

    typedef struct _GDataYouTubeVideo GDataYouTubeVideo;

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

### GDataYouTubeVideoClass

    typedef struct {
    } GDataYouTubeVideoClass;

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

### enum GDataYouTubeAspectRatio

    typedef enum {
    	GDATA_YOUTUBE_ASPECT_RATIO_UNKNOWN = 0,
    	GDATA_YOUTUBE_ASPECT_RATIO_WIDESCREEN
    } GDataYouTubeAspectRatio;

The aspect ratio of a video. See the online documentation for more information.

`GDATA_YOUTUBE_ASPECT_RATIO_UNKNOWN` | unknown aspect ratio
`GDATA_YOUTUBE_ASPECT_RATIO_WIDESCREEN` | widescreen (16:9) video

Since 0.4.0

### gdata_youtube_video_new ()

    GDataYouTubeVideo * gdata_youtube_video_new             (const gchar *id);

Creates a new GDataYouTubeVideo with the given ID and default properties.

`id` : | the video's ID, or `NULL`
Returns : | a new GDataYouTubeVideo; unref with `g_object_unref()`

### gdata_youtube_video_look_up_content ()

    GDataYouTubeContent * gdata_youtube_video_look_up_content
                                                            (GDataYouTubeVideo *self,
                                                             const gchar *type);

Looks up a GDataYouTubeContent from the video with the given MIME type. The video's list of contents is a list of URIs to various formats of the video itself, such as its SWF URI or RTSP stream.

`self` : | a GDataYouTubeVideo
`type` : | the MIME type of the content desired
Returns : | a GDataYouTubeContent matching `type`, or `NULL`. [transfer none]

### gdata_youtube_video_get_thumbnails ()

    GList *             gdata_youtube_video_get_thumbnails  (GDataYouTubeVideo *self);

Gets a list of the thumbnails available for the video.

`self` : | a GDataYouTubeVideo
Returns : | a GList of GDataMediaThumbnails, or `NULL`. [element-type GData.MediaThumbnail][transfer none]

### gdata_youtube_video_get_category ()

    GDataMediaCategory * gdata_youtube_video_get_category   (GDataYouTubeVideo *self);

Gets the "category" property.

`self` : | a GDataYouTubeVideo
Returns : | a GDataMediaCategory giving the video's single and mandatory category. [transfer none]

### gdata_youtube_video_set_category ()

    void                gdata_youtube_video_set_category    (GDataYouTubeVideo *self,
                                                             GDataMediaCategory *category);

Sets the "category" property to the new category, `category`, and increments its reference count.

`category` must not be `NULL`. For more information, see the online documentation.

`self` : | a GDataYouTubeVideo
`category` : | a new GDataMediaCategory

### gdata_youtube_video_get_credit ()

    GDataYouTubeCredit * gdata_youtube_video_get_credit     (GDataYouTubeVideo *self);

Gets the "credit" property.

`self` : | a GDataYouTubeVideo
Returns : | a GDataMediaCredit giving information on whom to credit for the video, or `NULL`. [transfer none]

### gdata_youtube_video_get_description ()

    const gchar *       gdata_youtube_video_get_description (GDataYouTubeVideo *self);

Gets the "description" property.

`self` : | a GDataYouTubeVideo
Returns : | the video's long text description, or `NULL`

### gdata_youtube_video_set_description ()

    void                gdata_youtube_video_set_description (GDataYouTubeVideo *self,
                                                             const gchar *description);

Sets the "description" property to the new description, `description`.

Set `description` to `NULL` to unset the video's description.

`self` : | a GDataYouTubeVideo
`description` : | the video's new description, or `NULL`. [allow-none]

### gdata_youtube_video_get_duration ()

    guint               gdata_youtube_video_get_duration    (GDataYouTubeVideo *self);

Gets the "duration" property.

`self` : | a GDataYouTubeVideo
Returns : | the video duration in seconds, or `0` if unknown

### gdata_youtube_video_get_keywords ()

    const gchar *       gdata_youtube_video_get_keywords    (GDataYouTubeVideo *self);

Gets the "keywords" property.

`self` : | a GDataYouTubeVideo
Returns : | a comma-separated list of words associated with the video

### gdata_youtube_video_set_keywords ()

    void                gdata_youtube_video_set_keywords    (GDataYouTubeVideo *self,
                                                             const gchar *keywords);

Sets the "keywords" property to the new keyword list, `keywords`.

`keywords` must not be `NULL`. For more information, see the online documentation.

`self` : | a GDataYouTubeVideo
`keywords` : | a new comma-separated list of keywords

### gdata_youtube_video_get_location ()

    const gchar *       gdata_youtube_video_get_location    (GDataYouTubeVideo *self);

Gets the "location" property.

`self` : | a GDataYouTubeVideo
Returns : | a string describing the video's location, or `NULL`

### gdata_youtube_video_set_location ()

    void                gdata_youtube_video_set_location    (GDataYouTubeVideo *self,
                                                             const gchar *location);

Sets the "location" property to the new location string, `location`.

Set `location` to `NULL` to unset the property in the video.

`self` : | a GDataYouTubeVideo
`location` : | a new location, or `NULL`. [allow-none]

### gdata_youtube_video_get_view_count ()

    guint               gdata_youtube_video_get_view_count  (GDataYouTubeVideo *self);

Gets the "view-count" property.

`self` : | a GDataYouTubeVideo
Returns : | the number of times the video has been viewed

### gdata_youtube_video_get_favorite_count ()

    guint               gdata_youtube_video_get_favorite_count
                                                            (GDataYouTubeVideo *self);

Gets the "favorite-count" property.

`self` : | a GDataYouTubeVideo
Returns : | the number of users who have added the video to their favorites list

### gdata_youtube_video_is_restricted_in_country ()

    gboolean            gdata_youtube_video_is_restricted_in_country
                                                            (GDataYouTubeVideo *self,
                                                             const gchar *country);

Checks whether viewing of the video is restricted in `country`, either by its content rating, or by the request of the producer. The return value from this function is purely informational, and no obligation is assumed.

`self` : | a GDataYouTubeVideo
`country` : | an ISO 3166 two-letter country code to check
Returns : | `TRUE` if the video is restricted in `country`, `FALSE` otherwise

Since 0.4.0

### gdata_youtube_video_get_no_embed ()

    gboolean            gdata_youtube_video_get_no_embed    (GDataYouTubeVideo *self);

Gets the "no-embed" property.

`self` : | a GDataYouTubeVideo
Returns : | `TRUE` if the video cannot be embedded on web pages, `FALSE` otherwise

### gdata_youtube_video_set_no_embed ()

    void                gdata_youtube_video_set_no_embed    (GDataYouTubeVideo *self,
                                                             gboolean no_embed);

Sets the "no-embed" property to `no_embed`.

`self` : | a GDataYouTubeVideo
`no_embed` : | whether the video can be embedded

### gdata_youtube_video_get_player_uri ()

    const gchar *       gdata_youtube_video_get_player_uri  (GDataYouTubeVideo *self);

Gets the "player-uri" property.

`self` : | a GDataYouTubeVideo
Returns : | a URI where the video is playable in a web browser, or `NULL`

### gdata_youtube_video_is_private ()

    gboolean            gdata_youtube_video_is_private      (GDataYouTubeVideo *self);

Gets the "is-private" property.

`self` : | a GDataYouTubeVideo
Returns : | `TRUE` if the video is private, `FALSE` otherwise

### gdata_youtube_video_set_is_private ()

    void                gdata_youtube_video_set_is_private  (GDataYouTubeVideo *self,
                                                             gboolean is_private);

Sets the "is-private" property to decide whether the video is publicly viewable.

`self` : | a GDataYouTubeVideo
`is_private` : | whether the video is private

### gdata_youtube_video_is_draft ()

    gboolean            gdata_youtube_video_is_draft        (GDataYouTubeVideo *self);

Gets the "is-draft" property.

`self` : | a GDataYouTubeVideo
Returns : | `TRUE` if the video is a draft, `FALSE` otherwise

### gdata_youtube_video_set_is_draft ()

    void                gdata_youtube_video_set_is_draft    (GDataYouTubeVideo *self,
                                                             gboolean is_draft);

Sets the "is-draft" property to decide whether the video is a draft.

`self` : | a GDataYouTubeVideo
`is_draft` : | whether the video is a draft

### gdata_youtube_video_get_state ()

    GDataYouTubeState * gdata_youtube_video_get_state       (GDataYouTubeVideo *self);

Gets the "state" property.

For more information, see the online documentation.

`self` : | a GDataYouTubeVideo
Returns : | a GDataYouTubeState showing the state of the video, or `NULL`. [transfer none]

### gdata_youtube_video_get_rating ()

    void                gdata_youtube_video_get_rating      (GDataYouTubeVideo *self,
                                                             guint *min,
                                                             guint *max,
                                                             guint *count,
                                                             gdouble *average);

Gets various properties of the ratings on the video.

`self` : | a GDataYouTubeVideo
`min` : | return location for the minimum rating value, or `NULL`. [out caller-allocates][allow-none]
`max` : | return location for the maximum rating value, or `NULL`. [out caller-allocates][allow-none]
`count` : | return location for the number of ratings, or `NULL`. [out caller-allocates][allow-none]
`average` : | return location for the average rating value, or `NULL`. [out caller-allocates][allow-none]

### gdata_youtube_video_get_uploaded ()

    void                gdata_youtube_video_get_uploaded    (GDataYouTubeVideo *self,
                                                             GTimeVal *uploaded);

Gets the "uploaded" property and puts it in `uploaded`. If the property is unset, both fields in the GTimeVal will be set to `0`.

`self` : | a GDataYouTubeVideo
`uploaded` : | a GTimeVal. [out caller-allocates]

### gdata_youtube_video_get_recorded ()

    void                gdata_youtube_video_get_recorded    (GDataYouTubeVideo *self,
                                                             GTimeVal *recorded);

Gets the "recorded" property and puts it in `recorded`. If the property is unset, both fields in the GTimeVal will be set to `0`.

`self` : | a GDataYouTubeVideo
`recorded` : | a GTimeVal. [out caller-allocates]

Since 0.3.0

### gdata_youtube_video_set_recorded ()

    void                gdata_youtube_video_set_recorded    (GDataYouTubeVideo *self,
                                                             GTimeVal *recorded);

Sets the "recorded" property to the new recorded time, `recorded`.

Set `recorded` to `NULL` to unset the video's recorded time.

`self` : | a GDataYouTubeVideo
`recorded` : | the video's new recorded time, or `NULL`. [allow-none]

Since 0.3.0

### gdata_youtube_video_get_video_id ()

    const gchar *       gdata_youtube_video_get_video_id    (GDataYouTubeVideo *self);

Gets the "video-id" property.

`self` : | a GDataYouTubeVideo
Returns : | the video's unique and permanent ID

### gdata_youtube_video_get_video_id_from_uri ()

    gchar *             gdata_youtube_video_get_video_id_from_uri
                                                            (const gchar *video_uri);

Extracts a video ID from a YouTube video player URI. The video ID is in the same form as returned by `gdata_youtube_video_get_video_id()`, and the `video_uri` should be in the same form as returned by `gdata_youtube_video_get_player_uri()`.

The function will validate whether the URI actually points to a hostname containing `youtube` (e.g. `youtube.com`), and will return `NULL` if it doesn't.

For example:

    1
    2
    3
    video_id = gdata_youtube_video_get_video_id_from_uri ("http://www.youtube.com/watch?v=BH_vwsyCrTc&feature=featured");
    g_message ("Video ID: %s", video_id); /* Should print: BH_vwsyCrTc */
    g_free (video_id);

`video_uri` : | a YouTube video player URI
Returns : | the video ID, or `NULL`; free with `g_free()`

Since 0.4.0

### gdata_youtube_video_get_aspect_ratio ()

    GDataYouTubeAspectRatio  gdata_youtube_video_get_aspect_ratio
                                                            (GDataYouTubeVideo *self);

Gets the "aspect-ratio" property.

`self` : | a GDataYouTubeVideo
Returns : | the aspect ratio property

Since 0.4.0

### gdata_youtube_video_set_aspect_ratio ()

    void                gdata_youtube_video_set_aspect_ratio
                                                            (GDataYouTubeVideo *self,
                                                             GDataYouTubeAspectRatio aspect_ratio);

Sets the "aspect-ratio" property to specify the video's aspect ratio.

`self` : | a GDataYouTubeVideo
`aspect_ratio` : | the aspect ratio property, or `NULL`. [allow-none]

Since 0.4.0

## Property Details

### The `"aspect-ratio"` property

      "aspect-ratio"             GDataYouTubeAspectRatio  : Read / Write

The aspect ratio of the video.

For more information see the online documentation.

Default value: GDATA_YOUTUBE_ASPECT_RATIO_UNKNOWN

Since 0.4.0

### The `"average-rating"` property

      "average-rating"           gdouble               : Read

The average rating of the video, over all the ratings it's received.

For more information, see the online documentation.

Allowed values: >= 0

Default value: 0

### The `"category"` property

      "category"                 GDataMediaCategory*   : Read / Write

Specifies a genre or developer tag that describes the video.

For more information, see the online documentation.

### The `"credit"` property

      "credit"                   GDataYouTubeCredit*   : Read

Identifies the owner of the video.

For more information, see the online documentation.

### The `"description"` property

      "description"              gchar*                : Read / Write

A summary or description of the video.

For more information, see the online documentation.

Default value: NULL

### The `"duration"` property

      "duration"                 guint                 : Read

The duration of the video in seconds.

For more information, see the online documentation.

Allowed values: <= G_MAXINT

Default value: 0

### The `"favorite-count"` property

      "favorite-count"           guint                 : Read

The number of YouTube users who have added the video to their list of favorite videos.

For more information, see the online documentation.

Default value: 0

### The `"is-draft"` property

      "is-draft"                 gboolean              : Read / Write

Indicates whether the video is in draft, or unpublished, status.

For more information, see the online documentation.

Default value: FALSE

### The `"is-private"` property

      "is-private"               gboolean              : Read / Write

Indicates whether the video is private.

Default value: FALSE

### The `"keywords"` property

      "keywords"                 gchar*                : Read / Write

A comma-separated list of words associated with the video.

For more information, see the online documentation.

Default value: NULL

### The `"location"` property

      "location"                 gchar*                : Read / Write

Descriptive text about the location where the video was taken.

For more information, see the online documentation.

Default value: NULL

### The `"max-rating"` property

      "max-rating"               guint                 : Read

The maximum allowed rating for the video.

For more information, see the online documentation.

Default value: 5

### The `"min-rating"` property

      "min-rating"               guint                 : Read

The minimum allowed rating for the video.

For more information, see the online documentation.

Default value: 1

### The `"no-embed"` property

      "no-embed"                 gboolean              : Read / Write

Specifies whether the video may not be embedded on other websites.

For more information, see the online documentation.

Default value: FALSE

### The `"player-uri"` property

      "player-uri"               gchar*                : Read

Specifies a URI where the full-length video is available through a media player that runs inside a web browser (i.e. the video's page on YouTube).

For more information, see the online documentation.

Default value: NULL

### The `"rating-count"` property

      "rating-count"             guint                 : Read

The number of times the video has been rated.

For more information, see the online documentation.

Default value: 0

### The `"recorded"` property

      "recorded"                 GDataTimeVal*         : Read / Write

Specifies the time the video was originally recorded.

For more information, see the online documentation.

Since 0.3.0

### The `"state"` property

      "state"                    GDataYouTubeState*    : Read

Information describing the state of the video. If this is non-`NULL`, the video is not playable. It points to a GDataYouTubeState.

For more information, see the online documentation.

### The `"uploaded"` property

      "uploaded"                 GDataTimeVal*         : Read

Specifies the time the video was originally uploaded to YouTube.

For more information, see the online documentation.

### The `"video-id"` property

      "video-id"                 gchar*                : Read

Specifies a unique ID which YouTube uses to identify the video. For example: `qz8EfkS4KK0`.

For more information, see the online documentation.

Default value: NULL

### The `"view-count"` property

      "view-count"               guint                 : Read

The number of times the video has been viewed.

For more information, see the online documentation.

Default value: 0