#define __GST_TAGLIST_H__
#include <gst/gstdatetime.h>
+#include <gst/gstsample.h>
#include <gst/gstbuffer.h>
-#include <gst/gststructure.h>
#include <gst/glib-compat.h>
G_BEGIN_DECLS
*
* Extra tag flags used when registering tags.
*/
+/* FIXME: these are not really flags .. */
typedef enum {
GST_TAG_FLAG_UNDEFINED,
GST_TAG_FLAG_META,
#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:
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);
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);
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,
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);
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);
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:
*
* 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:
*
/**
* 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
* 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
*/
/**
* 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)
*
projects / platform / upstream / gstreamer.git / blobdiff