X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gst%2Fgsttaglist.h;h=7940a3103f63452bc5b12620a97cf76ff63e9127;hb=066b515985897495cae32fca5b7eeeec260c40c9;hp=0cec0335abc27a1abb520730ff8f78c3a32c99d0;hpb=c8380cb0d291d537b05bddb26061e9ca095cf62f;p=platform%2Fupstream%2Fgstreamer.git diff --git a/gst/gsttaglist.h b/gst/gsttaglist.h index 0cec033..7940a31 100644 --- a/gst/gsttaglist.h +++ b/gst/gsttaglist.h @@ -24,8 +24,8 @@ #define __GST_TAGLIST_H__ #include +#include #include -#include #include G_BEGIN_DECLS @@ -132,6 +132,7 @@ typedef enum { * * Extra tag flags used when registering tags. */ +/* FIXME: these are not really flags .. */ typedef enum { GST_TAG_FLAG_UNDEFINED, GST_TAG_FLAG_META, @@ -142,28 +143,20 @@ typedef enum { #define GST_TAG_FLAG_IS_VALID(flag) (((flag) > GST_TAG_FLAG_UNDEFINED) && ((flag) < GST_TAG_FLAG_COUNT)) -/* FIXME 0.11: Don't typedef GstTagList to be a GstStructure, they're - * internally the same but not from an API point of view. - * See bug #518934. - */ /** * GstTagList: + * @mini_object: the parent type * - * Opaque #GstTagList data structure. + * Object describing tags / metadata. */ -#ifdef _FOOL_GTK_DOC_ typedef struct _GstTagList GstTagList; -#else -#ifdef IN_GOBJECT_INTROSPECTION -typedef struct _GstTagList GstTagList; -#else -typedef GstStructure GstTagList; -#endif -#endif +struct _GstTagList { + GstMiniObject mini_object; +}; #define GST_TAG_LIST(x) ((GstTagList *) (x)) -#define GST_IS_TAG_LIST(x) ((x) != NULL && gst_is_tag_list (GST_TAG_LIST (x))) #define GST_TYPE_TAG_LIST (gst_tag_list_get_type ()) +#define GST_IS_TAG_LIST(obj) (GST_IS_MINI_OBJECT_TYPE((obj), GST_TYPE_TAG_LIST)) /** * GstTagForeachFunc: @@ -198,6 +191,13 @@ void gst_tag_register (const gchar * name, const gchar * blurb, GstTagMergeFunc func); +void gst_tag_register_static (const gchar * name, + GstTagFlag flag, + GType type, + const gchar * nick, + const gchar * blurb, + GstTagMergeFunc func); + /* some default merging functions */ void gst_tag_merge_use_first (GValue * dest, const GValue * src); void gst_tag_merge_strings_with_comma (GValue * dest, const GValue * src); @@ -211,15 +211,15 @@ GstTagFlag gst_tag_get_flag (const gchar * tag); gboolean gst_tag_is_fixed (const gchar * tag); /* tag lists */ -GstTagList * gst_tag_list_new (void) G_GNUC_MALLOC; -GstTagList * gst_tag_list_new_full (const gchar * tag, ...) G_GNUC_MALLOC; -GstTagList * gst_tag_list_new_full_valist (va_list var_args) G_GNUC_MALLOC; +GstTagList * gst_tag_list_new_empty (void) G_GNUC_MALLOC; +GstTagList * gst_tag_list_new (const gchar * tag, ...) G_GNUC_MALLOC; +GstTagList * gst_tag_list_new_valist (va_list var_args) G_GNUC_MALLOC; gchar * gst_tag_list_to_string (const GstTagList * list) G_GNUC_MALLOC; GstTagList * gst_tag_list_new_from_string (const gchar * str) G_GNUC_MALLOC; -gboolean gst_is_tag_list (gconstpointer p); -GstTagList * gst_tag_list_copy (const GstTagList * list) G_GNUC_MALLOC; +gint gst_tag_list_n_tags (const GstTagList * list); +const gchar* gst_tag_list_nth_tag_name (const GstTagList * list, guint index); gboolean gst_tag_list_is_empty (const GstTagList * list); gboolean gst_tag_list_is_equal (const GstTagList * list1, const GstTagList * list2); @@ -229,7 +229,6 @@ void gst_tag_list_insert (GstTagList * into, GstTagList * gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2, GstTagMergeMode mode) G_GNUC_MALLOC; -void gst_tag_list_free (GstTagList * list); guint gst_tag_list_get_tag_size (const GstTagList * list, const gchar * tag); void gst_tag_list_add (GstTagList * list, @@ -267,20 +266,6 @@ gboolean gst_tag_list_copy_value (GValue * dest, const gchar * tag); /* simplifications (FIXME: do we want them?) */ -gboolean gst_tag_list_get_char (const GstTagList * list, - const gchar * tag, - gchar * value); -gboolean gst_tag_list_get_char_index (const GstTagList * list, - const gchar * tag, - guint index, - gchar * value); -gboolean gst_tag_list_get_uchar (const GstTagList * list, - const gchar * tag, - guchar * value); -gboolean gst_tag_list_get_uchar_index (const GstTagList * list, - const gchar * tag, - guint index, - guchar * value); gboolean gst_tag_list_get_boolean (const GstTagList * list, const gchar * tag, gboolean * value); @@ -302,20 +287,6 @@ gboolean gst_tag_list_get_uint_index (const GstTagList * list, const gchar * tag, guint index, guint * value); -gboolean gst_tag_list_get_long (const GstTagList * list, - const gchar * tag, - glong * value); -gboolean gst_tag_list_get_long_index (const GstTagList * list, - const gchar * tag, - guint index, - glong * value); -gboolean gst_tag_list_get_ulong (const GstTagList * list, - const gchar * tag, - gulong * value); -gboolean gst_tag_list_get_ulong_index (const GstTagList * list, - const gchar * tag, - guint index, - gulong * value); gboolean gst_tag_list_get_int64 (const GstTagList * list, const gchar * tag, gint64 * value); @@ -384,6 +355,104 @@ gboolean gst_tag_list_get_buffer_index (const GstTagList * list, guint index, GstBuffer ** value); +/* refcounting */ +/** + * gst_tag_list_ref: + * @taglist: the #GstTagList to reference + * + * Add a reference to a #GstTagList mini object. + * + * From this point on, until the caller calls gst_tag_list_unref() or + * gst_tag_list_make_writable(), it is guaranteed that the taglist object will + * not change. To use a #GstTagList object, you must always have a refcount on + * it -- either the one made implicitly by e.g. gst_tag_list_new(), or via + * taking one explicitly with this function. + * + * Returns: the same #GstTagList mini object. + */ +#ifdef _FOOL_GTK_DOC_ +G_INLINE_FUNC GstTagList * gst_tag_list_ref (GstTagList * taglist); +#endif + +static inline GstTagList * +gst_tag_list_ref (GstTagList * taglist) +{ + return (GstTagList *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (taglist)); +} + +/** + * gst_tag_list_unref: + * @taglist: a #GstTagList. + * + * Unref a #GstTagList, and and free all its memory when the refcount reaches 0. + */ +#ifdef _FOOL_GTK_DOC_ +G_INLINE_FUNC void gst_tag_list_unref (GstTagList * taglist); +#endif + +static inline void +gst_tag_list_unref (GstTagList * taglist) +{ + gst_mini_object_unref (GST_MINI_OBJECT_CAST (taglist)); +} + +/** + * gst_tag_list_copy: + * @taglist: a #GstTagList. + * + * Creates a new #GstTagList as a copy of the old @taglist. The new taglist + * will have a refcount of 1, owned by the caller, and will be writable as + * a result. + * + * Note that this function is the semantic equivalent of a gst_tag_list_ref() + * followed by a gst_tag_list_make_writable(). If you only want to hold on to a + * reference to the data, you should use gst_tag_list_ref(). + * + * When you are finished with the taglist, call gst_tag_list_unref() on it. + * + * Returns: the new #GstTagList + */ +#ifdef _FOOL_GTK_DOC_ +G_INLINE_FUNC GstTagList * gst_tag_list_copy (const GstTagList * taglist); +#endif + +static inline GstTagList * +gst_tag_list_copy (const GstTagList * taglist) +{ + return GST_TAG_LIST (gst_mini_object_copy (GST_MINI_OBJECT_CAST (taglist))); +} + +/** + * gst_tag_list_is_writable: + * @taglist: a #GstTagList + * + * Tests if you can safely modify @taglist. It is only safe to modify taglist + * when there is only one owner of the taglist - ie, the refcount is 1. + */ +#define gst_tag_list_is_writable(taglist) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (taglist)) + +/** + * gst_tag_list_make_writable: + * @taglist: (transfer full): a #GstTagList + * + * Returns a writable copy of @taglist. + * + * If there is only one reference count on @taglist, the caller must be the + * owner, and so this function will return the taglist object unchanged. If on + * the other hand there is more than one reference on the object, a new taglist + * object will be returned (which will be a copy of @taglist). The caller's + * reference on @taglist will be removed, and instead the caller will own a + * reference to the returned object. + * + * In short, this function unrefs the taglist in the argument and refs the + * taglist that it returns. Don't access the argument after calling this + * function. See also: gst_tag_list_ref(). + * + * Returns: (transfer full): a writable taglist which may or may not be the + * same as @taglist + */ +#define gst_tag_list_make_writable(taglist) GST_TAG_LIST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (taglist))) + /* GStreamer core tags */ /** * GST_TAG_TITLE: @@ -422,8 +491,7 @@ gboolean gst_tag_list_get_buffer_index (const GstTagList * list, * * Since: 0.10.15 */ -/* FIXME 0.11: change to "artist-sortname" */ -#define GST_TAG_ARTIST_SORTNAME "musicbrainz-sortname" +#define GST_TAG_ARTIST_SORTNAME "artist-sortname" /** * GST_TAG_ALBUM: * @@ -741,13 +809,28 @@ gboolean gst_tag_list_get_buffer_index (const GstTagList * list, /** * GST_TAG_LANGUAGE_CODE: * - * Language code (ISO-639-1) (string) of the content + * ISO-639-2 or ISO-639-1 code for the language the content is in (string) + * + * There is utility API in libgsttag in gst-plugins-base to obtain a translated + * language name from the language code: gst_tag_get_language_name() */ #define GST_TAG_LANGUAGE_CODE "language-code" /** + * GST_TAG_LANGUAGE_NAME: + * + * Name of the language the content is in (string) + * + * Free-form name of the language the content is in, if a language code + * is not available. This tag should not be set in addition to a language + * code. It is undefined what language or locale the language name is in. + * + * Since: 0.10.37 + */ +#define GST_TAG_LANGUAGE_NAME "language-name" +/** * GST_TAG_IMAGE: * - * image (buffer) (buffer caps should specify the content type and preferably + * image (sample) (sample taglist should specify the content type and preferably * also set "image-type" field as #GstTagImageType) * * Since: 0.10.6 @@ -757,7 +840,7 @@ gboolean gst_tag_list_get_buffer_index (const GstTagList * list, * GST_TAG_PREVIEW_IMAGE: * * image that is meant for preview purposes, e.g. small icon-sized version - * (buffer) (buffer caps should specify the content type) + * (sample) (sample taglist should specify the content type) * * Since: 0.10.7 */ @@ -766,7 +849,7 @@ gboolean gst_tag_list_get_buffer_index (const GstTagList * list, /** * GST_TAG_ATTACHMENT: * - * generic file attachment (buffer) (buffer caps should specify the content + * generic file attachment (sample) (sample taglist should specify the content * type and if possible set "filename" to the file name of the * attachment) *