Media RSS API

Media RSS API — Media RSS namespace API

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <gdata/gdata-media-rss.h>

                    GDataMediaCategory;
GDataMediaCategory * gdata_media_category_new           (const gchar *category,
                                                         const gchar *label,
                                                         const gchar *scheme);
void                gdata_media_category_free           (GDataMediaCategory *self);
enum                GDataMediaExpression;
                    GDataMediaContent;
GDataMediaContent * gdata_media_content_new             (const gchar *uri,
                                                         const gchar *type,
                                                         gboolean is_default,
                                                         GDataMediaExpression expression,
                                                         gint duration,
                                                         gint format);
void                gdata_media_content_free            (GDataMediaContent *self);
                    GDataMediaCredit;
GDataMediaCredit *  gdata_media_credit_new              (const gchar *credit,
                                                         gboolean partner);
void                gdata_media_credit_free             (GDataMediaCredit *self);
                    GDataMediaRating;
GDataMediaRating *  gdata_media_rating_new              (const gchar *scheme,
                                                         const gchar *country);
void                gdata_media_rating_free             (GDataMediaRating *self);
                    GDataMediaRestriction;
GDataMediaRestriction * gdata_media_restriction_new     (const gchar *countries,
                                                         gboolean relationship);
void                gdata_media_restriction_free        (GDataMediaRestriction *self);
                    GDataMediaThumbnail;
GDataMediaThumbnail * gdata_media_thumbnail_new         (const gchar *uri,
                                                         guint width,
                                                         guint height,
                                                         gint64 _time);
void                gdata_media_thumbnail_free          (GDataMediaThumbnail *self);
gint64              gdata_media_thumbnail_parse_time    (const gchar *time_string);
gchar *             gdata_media_thumbnail_build_time    (gint64 _time);

Description

The structures here represent several core elements in the Media RSS specification which are used in some media-related GData APIs, in particular the YouTube API.

Details

GDataMediaCategory

typedef struct {
	gchar *category;
	gchar *label;
	gchar *scheme;
} GDataMediaCategory;

A structure fully representing a Media RSS "category" element. The category field is required, but the others are optional.

See the media:category element in the Media RSS specification for more information.

gchar *category;

a category describing the content

gchar *label;

a human-readable name for the category, or NULL

gchar *scheme;

a URI identifying the categorisation scheme, or NULL

gdata_media_category_new ()

GDataMediaCategory * gdata_media_category_new           (const gchar *category,
                                                         const gchar *label,
                                                         const gchar *scheme);

Creates a new GDataMediaCategory. More information is available in the Media RSS specification.

category :

a category describing the content

label :

a human-readable name for the category, or NULL

scheme :

a URI identifying the categorisation scheme, or NULL

Returns :

a new GDataMediaCategory, or NULL; free with gdata_media_category_free()

gdata_media_category_free ()

void                gdata_media_category_free           (GDataMediaCategory *self);

Frees a GDataMediaCategory.

self :

a GDataMediaCategory

enum GDataMediaExpression

typedef enum {
	GDATA_MEDIA_EXPRESSION_SAMPLE,
	GDATA_MEDIA_EXPRESSION_FULL,
	GDATA_MEDIA_EXPRESSION_NONSTOP
} GDataMediaExpression;

An enum representing the possible values of "expression".

GDATA_MEDIA_EXPRESSION_SAMPLE

the media is a sample of a larger video

GDATA_MEDIA_EXPRESSION_FULL

the media is the full version

GDATA_MEDIA_EXPRESSION_NONSTOP

the media is a continuous stream

GDataMediaContent

typedef struct {
	gchar *uri;
	gchar *type;
	gboolean is_default;
	GDataMediaExpression expression;
	gint duration; /* TODO: Should be guint? */
	gint format; /* TODO: YouTube-specific */
	/* TODO: add support for other standard properties */
} GDataMediaContent;

A structure fully representing a Media RSS "content" element. The uri field is required, but the others are optional.

See the media:content element in the Media RSS specification for more information.

gchar *uri;

the media object's URI

gchar *type;

the media object's MIME type, or NULL

gboolean is_default;

TRUE if this is the default object for the media group, FALSE otherwise

GDataMediaExpression expression;

whether this media is a full version or just a sample

gint duration;

the length of the media, in seconds, or -1

gint format;

the video format of the media (see the YouTube specification)

gdata_media_content_new ()

GDataMediaContent * gdata_media_content_new             (const gchar *uri,
                                                         const gchar *type,
                                                         gboolean is_default,
                                                         GDataMediaExpression expression,
                                                         gint duration,
                                                         gint format);

Creates a new GDataMediaContent. More information is available in the Media RSS specification.

uri :

the media object's URI

type :

the media object's MIME type, or NULL

is_default :

TRUE if this is the default object for the media group, FALSE otherwise

expression :

whether this media is a full version or just a sample

duration :

the length of the media, in seconds, or -1

format :

the video format of the media (see the YouTube specification)

Returns :

a new GDataMediaContent, or NULL; free with gdata_media_content_free()

gdata_media_content_free ()

void                gdata_media_content_free            (GDataMediaContent *self);

Frees a GDataMediaContent.

self :

a GDataMediaContent

GDataMediaCredit

typedef struct {
	gchar *credit;
	gboolean partner;
	/* TODO: add scheme and role */
	/* TODO: partner is YouTube-specific */
} GDataMediaCredit;

A structure fully representing a Media RSS "credit" element. All fields are required.

See the media:credit element in the Media RSS specification for more information.

gchar *credit;

the username of someone who contributed towards the media

gboolean partner;

TRUE if the video was uploaded by a YouTube partner, FALSE otherwise

gdata_media_credit_new ()

GDataMediaCredit *  gdata_media_credit_new              (const gchar *credit,
                                                         gboolean partner);

Creates a new GDataMediaCredit. More information is available in the Media RSS specification.

credit :

the username of someone who contributed towards the media

partner :

TRUE if the video was uploaded by a YouTube partner, FALSE otherwise

Returns :

a new GDataMediaCredit, or NULL; free with gdata_media_credit_free()

gdata_media_credit_free ()

void                gdata_media_credit_free             (GDataMediaCredit *self);

Frees a GDataMediaCredit.

self :

a GDataMediaCredit

GDataMediaRating

typedef struct {
	gchar *country;
	gchar *scheme;
} GDataMediaRating;

A structure fully representing a Media RSS "rating" element. The country field is required, but the other is optional.

See the media:rating element in the Media RSS specification for more information.

gchar *country;

a comma-delimited list of ISO 3166 country codes where the content is restricted

gchar *scheme;

a URI identifying the rating scheme, or NULL

gdata_media_rating_new ()

GDataMediaRating *  gdata_media_rating_new              (const gchar *scheme,
                                                         const gchar *country);

Creates a new GDataMediaRating. More information is available in the Media RSS specification.

scheme :

a URI identifying the rating scheme, or NULL

country :

a comma-delimited list of ISO 3166 country codes where the content is restricted

Returns :

a new GDataMediaRating, or NULL; free with gdata_media_rating_free()

gdata_media_rating_free ()

void                gdata_media_rating_free             (GDataMediaRating *self);

Frees a GDataMediaRating.

self :

a GDataMediaRating

GDataMediaRestriction

typedef struct {
	gchar *countries;
	gboolean relationship;
	/* TODO: Support uri and type */
} GDataMediaRestriction;

A structure fully representing a Media RSS "restriction" element. All fields are required.

See the media:restriction element in the Media RSS specification for more information.

gchar *countries;

a space-delimited list of ISO 3166 country codes

gboolean relationship;

TRUE if the given countries are not restricted regarding the content, FALSE otherwise

gdata_media_restriction_new ()

GDataMediaRestriction * gdata_media_restriction_new     (const gchar *countries,
                                                         gboolean relationship);

Creates a new GDataMediaRestriction. More information is available in the Media RSS specification.

countries :

a space-delimited list of ISO 3166 country codes

relationship :

TRUE if the given countries are not restricted regarding the content, FALSE otherwise

Returns :

a new GDataMediaRestriction, or NULL; free with gdata_media_restriction_free()

gdata_media_restriction_free ()

void                gdata_media_restriction_free        (GDataMediaRestriction *self);

Frees a GDataMediaRestriction.


GDataMediaThumbnail

typedef struct {
	gchar *uri;
	guint width;
	guint height;
	gint64 time;
} GDataMediaThumbnail;

A structure fully representing a Media RSS "thumbnail" element. The uri field is required, but the others are optional.

See the media:thumbnail element in the Media RSS specification for more information.

gchar *uri;

the thumbnail's URI

guint width;

the thumbnail's width, in pixels, or 0

guint height;

the thumbnail's height, in pixels, or 0

gint64 time;

the number of milliseconds into the media the thumbnail was taken, or 0

gdata_media_thumbnail_new ()

GDataMediaThumbnail * gdata_media_thumbnail_new         (const gchar *uri,
                                                         guint width,
                                                         guint height,
                                                         gint64 _time);

Creates a new GDataMediaThumbnail. More information is available in the Media RSS specification.

uri :

the thumbnail's URI

width :

the thumbnail's width, in pixels, or 0

height :

the thumbnail's height, in pixels, or 0

_time :

the number of milliseconds into the media the thumbnail was taken, or 0

Returns :

a new GDataMediaThumbnail, or NULL; free with gdata_media_thumbnail_free()

gdata_media_thumbnail_free ()

void                gdata_media_thumbnail_free          (GDataMediaThumbnail *self);

Frees a GDataMediaThumbnail.


gdata_media_thumbnail_parse_time ()

gint64              gdata_media_thumbnail_parse_time    (const gchar *time_string);

Parses a time string in NTP format into a number of milliseconds since the start of a media stream.

For more information about NTP format, see RFC 2326 3.6 Normal Play Time.

To build an NTP-format string, see gdata_media_thumbnail_build_time().

time_string :

a time string to parse

Returns :

number of milliseconds since the start of a media stream

gdata_media_thumbnail_build_time ()

gchar *             gdata_media_thumbnail_build_time    (gint64 _time);

Builds an NTP-format time string describing _time milliseconds since the start of a media stream.

_time :

a number of milliseconds since the start of a media stream

Returns :

an NTP-format string describing _time; free with g_free()