gst/gsttaglist.c

   1 /* GStreamer
   2  * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
   3  *
   4  * gsttaglist.c: tag support (aka metadata)
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 /**
  23  * SECTION:gsttaglist
  24  * @short_description: List of tags and values used to describe media metadata
  25  *
  26  * List of tags and values used to describe media metadata.
  27  *
  28  * Strings must be in ASCII or UTF-8 encoding. No other encodings are allowed.
  29  *
  30  * Last reviewed on 2009-06-09 (0.10.23)
  31  */
  32
  33 #ifdef HAVE_CONFIG_H
  34 #  include "config.h"
  35 #endif
  36
  37 #include "gst_private.h"
  38 #include "math-compat.h"
  39 #include "gst-i18n-lib.h"
  40 #include "gsttaglist.h"
  41 #include "gstinfo.h"
  42 #include "gstvalue.h"
  43 #include "gstbuffer.h"
  44 #include "gstquark.h"
  45 #include "gststructure.h"
  46
  47 #include <gobject/gvaluecollector.h>
  48 #include <string.h>
  49
  50 #define GST_TAG_IS_VALID(tag)           (gst_tag_get_info (tag) != NULL)
  51
  52 /* FIXME 0.11: make taglists refcounted maybe? */
  53 /* a tag list is basically a structure, but we don't make this fact public */
  54 struct _GstTagList
  55 {
  56   GstStructure structure;
  57 };
  58
  59 /* FIXME 0.11: use GParamSpecs or something similar for tag registrations,
  60  * possibly even gst_tag_register(). Especially value ranges might be
  61  * useful for some tags. */
  62
  63 typedef struct
  64 {
  65   GType type;                   /* type the data is in */
  66
  67   gchar *nick;                  /* translated name */
  68   gchar *blurb;                 /* translated description of type */
  69
  70   GstTagMergeFunc merge_func;   /* functions to merge the values */
  71   GstTagFlag flag;              /* type of tag */
  72   GQuark name_quark;            /* quark for the name */
  73 }
  74 GstTagInfo;
  75
  76 #define g_value_get_char g_value_get_schar
  77
  78 static GMutex __tag_mutex;
  79 #define TAG_LOCK g_mutex_lock (&__tag_mutex)
  80 #define TAG_UNLOCK g_mutex_unlock (&__tag_mutex)
  81
  82 /* tags hash table: maps tag name string => GstTagInfo */
  83 static GHashTable *__tags;
  84
  85 G_DEFINE_BOXED_TYPE (GstTagList, gst_tag_list,
  86     (GBoxedCopyFunc) gst_tag_list_copy, (GBoxedFreeFunc) gst_tag_list_free);
  87
  88 /* FIXME: had code:
  89  *    g_value_register_transform_func (_gst_tag_list_type, G_TYPE_STRING,
  90  *      _gst_structure_transform_to_string);
  91  */
  92
  93 void
  94 _priv_gst_tag_initialize (void)
  95 {
  96   g_mutex_init (&__tag_mutex);
  97
  98   __tags = g_hash_table_new (g_str_hash, g_str_equal);
  99   gst_tag_register (GST_TAG_TITLE, GST_TAG_FLAG_META,
 100       G_TYPE_STRING,
 101       _("title"), _("commonly used title"), gst_tag_merge_strings_with_comma);
 102   gst_tag_register (GST_TAG_TITLE_SORTNAME, GST_TAG_FLAG_META,
 103       G_TYPE_STRING,
 104       _("title sortname"), _("commonly used title for sorting purposes"), NULL);
 105   gst_tag_register (GST_TAG_ARTIST, GST_TAG_FLAG_META,
 106       G_TYPE_STRING,
 107       _("artist"),
 108       _("person(s) responsible for the recording"),
 109       gst_tag_merge_strings_with_comma);
 110   gst_tag_register (GST_TAG_ARTIST_SORTNAME, GST_TAG_FLAG_META,
 111       G_TYPE_STRING,
 112       _("artist sortname"),
 113       _("person(s) responsible for the recording for sorting purposes"), NULL);
 114   gst_tag_register (GST_TAG_ALBUM, GST_TAG_FLAG_META,
 115       G_TYPE_STRING,
 116       _("album"),
 117       _("album containing this data"), gst_tag_merge_strings_with_comma);
 118   gst_tag_register (GST_TAG_ALBUM_SORTNAME, GST_TAG_FLAG_META,
 119       G_TYPE_STRING,
 120       _("album sortname"),
 121       _("album containing this data for sorting purposes"), NULL);
 122   gst_tag_register (GST_TAG_ALBUM_ARTIST, GST_TAG_FLAG_META,
 123       G_TYPE_STRING,
 124       _("album artist"),
 125       _("The artist of the entire album, as it should be displayed"),
 126       gst_tag_merge_strings_with_comma);
 127   gst_tag_register (GST_TAG_ALBUM_ARTIST_SORTNAME, GST_TAG_FLAG_META,
 128       G_TYPE_STRING,
 129       _("album artist sortname"),
 130       _("The artist of the entire album, as it should be sorted"), NULL);
 131   gst_tag_register (GST_TAG_DATE, GST_TAG_FLAG_META, G_TYPE_DATE,
 132       _("date"), _("date the data was created (as a GDate structure)"), NULL);
 133   gst_tag_register (GST_TAG_DATE_TIME, GST_TAG_FLAG_META, GST_TYPE_DATE_TIME,
 134       _("datetime"),
 135       _("date and time the data was created (as a GstDateTime structure)"),
 136       NULL);
 137   gst_tag_register (GST_TAG_GENRE, GST_TAG_FLAG_META,
 138       G_TYPE_STRING,
 139       _("genre"),
 140       _("genre this data belongs to"), gst_tag_merge_strings_with_comma);
 141   gst_tag_register (GST_TAG_COMMENT, GST_TAG_FLAG_META,
 142       G_TYPE_STRING,
 143       _("comment"),
 144       _("free text commenting the data"), gst_tag_merge_use_first);
 145   gst_tag_register (GST_TAG_EXTENDED_COMMENT, GST_TAG_FLAG_META,
 146       G_TYPE_STRING,
 147       _("extended comment"),
 148       _("free text commenting the data in key=value or key[en]=comment form"),
 149       gst_tag_merge_use_first);
 150   gst_tag_register (GST_TAG_TRACK_NUMBER, GST_TAG_FLAG_META,
 151       G_TYPE_UINT,
 152       _("track number"),
 153       _("track number inside a collection"), gst_tag_merge_use_first);
 154   gst_tag_register (GST_TAG_TRACK_COUNT, GST_TAG_FLAG_META,
 155       G_TYPE_UINT,
 156       _("track count"),
 157       _("count of tracks inside collection this track belongs to"),
 158       gst_tag_merge_use_first);
 159   gst_tag_register (GST_TAG_ALBUM_VOLUME_NUMBER, GST_TAG_FLAG_META,
 160       G_TYPE_UINT,
 161       _("disc number"),
 162       _("disc number inside a collection"), gst_tag_merge_use_first);
 163   gst_tag_register (GST_TAG_ALBUM_VOLUME_COUNT, GST_TAG_FLAG_META,
 164       G_TYPE_UINT,
 165       _("disc count"),
 166       _("count of discs inside collection this disc belongs to"),
 167       gst_tag_merge_use_first);
 168   gst_tag_register (GST_TAG_LOCATION, GST_TAG_FLAG_META,
 169       G_TYPE_STRING,
 170       _("location"), _("Origin of media as a URI (location, where the "
 171           "original of the file or stream is hosted)"),
 172       gst_tag_merge_strings_with_comma);
 173   gst_tag_register (GST_TAG_HOMEPAGE, GST_TAG_FLAG_META,
 174       G_TYPE_STRING,
 175       _("homepage"),
 176       _("Homepage for this media (i.e. artist or movie homepage)"),
 177       gst_tag_merge_strings_with_comma);
 178   gst_tag_register (GST_TAG_DESCRIPTION, GST_TAG_FLAG_META, G_TYPE_STRING,
 179       _("description"), _("short text describing the content of the data"),
 180       gst_tag_merge_strings_with_comma);
 181   gst_tag_register (GST_TAG_VERSION, GST_TAG_FLAG_META, G_TYPE_STRING,
 182       _("version"), _("version of this data"), NULL);
 183   gst_tag_register (GST_TAG_ISRC, GST_TAG_FLAG_META, G_TYPE_STRING, _("ISRC"),
 184       _
 185       ("International Standard Recording Code - see http://www.ifpi.org/isrc/"),
 186       NULL);
 187   /* FIXME: organization (fix what? tpm) */
 188   gst_tag_register (GST_TAG_ORGANIZATION, GST_TAG_FLAG_META, G_TYPE_STRING,
 189       _("organization"), _("organization"), gst_tag_merge_strings_with_comma);
 190   gst_tag_register (GST_TAG_COPYRIGHT, GST_TAG_FLAG_META,
 191       G_TYPE_STRING, _("copyright"), _("copyright notice of the data"), NULL);
 192   gst_tag_register (GST_TAG_COPYRIGHT_URI, GST_TAG_FLAG_META,
 193       G_TYPE_STRING, _("copyright uri"),
 194       _("URI to the copyright notice of the data"), NULL);
 195   gst_tag_register (GST_TAG_ENCODED_BY, GST_TAG_FLAG_META, G_TYPE_STRING,
 196       _("encoded by"), _("name of the encoding person or organization"),
 197       gst_tag_merge_strings_with_comma);
 198   gst_tag_register (GST_TAG_CONTACT, GST_TAG_FLAG_META,
 199       G_TYPE_STRING,
 200       _("contact"), _("contact information"), gst_tag_merge_strings_with_comma);
 201   gst_tag_register (GST_TAG_LICENSE, GST_TAG_FLAG_META,
 202       G_TYPE_STRING, _("license"), _("license of data"), NULL);
 203   gst_tag_register (GST_TAG_LICENSE_URI, GST_TAG_FLAG_META,
 204       G_TYPE_STRING, _("license uri"),
 205       _("URI to the license of the data"), NULL);
 206   gst_tag_register (GST_TAG_PERFORMER, GST_TAG_FLAG_META,
 207       G_TYPE_STRING,
 208       _("performer"),
 209       _("person(s) performing"), gst_tag_merge_strings_with_comma);
 210   gst_tag_register (GST_TAG_COMPOSER, GST_TAG_FLAG_META,
 211       G_TYPE_STRING,
 212       _("composer"),
 213       _("person(s) who composed the recording"),
 214       gst_tag_merge_strings_with_comma);
 215   gst_tag_register (GST_TAG_DURATION, GST_TAG_FLAG_DECODED,
 216       G_TYPE_UINT64,
 217       _("duration"), _("length in GStreamer time units (nanoseconds)"), NULL);
 218   gst_tag_register (GST_TAG_CODEC, GST_TAG_FLAG_ENCODED,
 219       G_TYPE_STRING,
 220       _("codec"),
 221       _("codec the data is stored in"), gst_tag_merge_strings_with_comma);
 222   gst_tag_register (GST_TAG_VIDEO_CODEC, GST_TAG_FLAG_ENCODED,
 223       G_TYPE_STRING,
 224       _("video codec"), _("codec the video data is stored in"), NULL);
 225   gst_tag_register (GST_TAG_AUDIO_CODEC, GST_TAG_FLAG_ENCODED,
 226       G_TYPE_STRING,
 227       _("audio codec"), _("codec the audio data is stored in"), NULL);
 228   gst_tag_register (GST_TAG_SUBTITLE_CODEC, GST_TAG_FLAG_ENCODED,
 229       G_TYPE_STRING,
 230       _("subtitle codec"), _("codec the subtitle data is stored in"), NULL);
 231   gst_tag_register (GST_TAG_CONTAINER_FORMAT, GST_TAG_FLAG_ENCODED,
 232       G_TYPE_STRING, _("container format"),
 233       _("container format the data is stored in"), NULL);
 234   gst_tag_register (GST_TAG_BITRATE, GST_TAG_FLAG_ENCODED,
 235       G_TYPE_UINT, _("bitrate"), _("exact or average bitrate in bits/s"), NULL);
 236   gst_tag_register (GST_TAG_NOMINAL_BITRATE, GST_TAG_FLAG_ENCODED,
 237       G_TYPE_UINT, _("nominal bitrate"), _("nominal bitrate in bits/s"), NULL);
 238   gst_tag_register (GST_TAG_MINIMUM_BITRATE, GST_TAG_FLAG_ENCODED,
 239       G_TYPE_UINT, _("minimum bitrate"), _("minimum bitrate in bits/s"), NULL);
 240   gst_tag_register (GST_TAG_MAXIMUM_BITRATE, GST_TAG_FLAG_ENCODED,
 241       G_TYPE_UINT, _("maximum bitrate"), _("maximum bitrate in bits/s"), NULL);
 242   gst_tag_register (GST_TAG_ENCODER, GST_TAG_FLAG_ENCODED,
 243       G_TYPE_STRING,
 244       _("encoder"), _("encoder used to encode this stream"), NULL);
 245   gst_tag_register (GST_TAG_ENCODER_VERSION, GST_TAG_FLAG_ENCODED,
 246       G_TYPE_UINT,
 247       _("encoder version"),
 248       _("version of the encoder used to encode this stream"), NULL);
 249   gst_tag_register (GST_TAG_SERIAL, GST_TAG_FLAG_ENCODED,
 250       G_TYPE_UINT, _("serial"), _("serial number of track"), NULL);
 251   gst_tag_register (GST_TAG_TRACK_GAIN, GST_TAG_FLAG_META,
 252       G_TYPE_DOUBLE, _("replaygain track gain"), _("track gain in db"), NULL);
 253   gst_tag_register (GST_TAG_TRACK_PEAK, GST_TAG_FLAG_META,
 254       G_TYPE_DOUBLE, _("replaygain track peak"), _("peak of the track"), NULL);
 255   gst_tag_register (GST_TAG_ALBUM_GAIN, GST_TAG_FLAG_META,
 256       G_TYPE_DOUBLE, _("replaygain album gain"), _("album gain in db"), NULL);
 257   gst_tag_register (GST_TAG_ALBUM_PEAK, GST_TAG_FLAG_META,
 258       G_TYPE_DOUBLE, _("replaygain album peak"), _("peak of the album"), NULL);
 259   gst_tag_register (GST_TAG_REFERENCE_LEVEL, GST_TAG_FLAG_META,
 260       G_TYPE_DOUBLE, _("replaygain reference level"),
 261       _("reference level of track and album gain values"), NULL);
 262   gst_tag_register (GST_TAG_LANGUAGE_CODE, GST_TAG_FLAG_META, G_TYPE_STRING,
 263       _("language code"),
 264       _("language code for this stream, conforming to ISO-639-1 or ISO-639-2"),
 265       NULL);
 266   gst_tag_register (GST_TAG_LANGUAGE_NAME, GST_TAG_FLAG_META, G_TYPE_STRING,
 267       _("language name"),
 268       _("freeform name of the language this stream is in"), NULL);
 269   gst_tag_register (GST_TAG_IMAGE, GST_TAG_FLAG_META, GST_TYPE_SAMPLE,
 270       _("image"), _("image related to this stream"), gst_tag_merge_use_first);
 271   gst_tag_register (GST_TAG_PREVIEW_IMAGE, GST_TAG_FLAG_META, GST_TYPE_SAMPLE,
 272       /* TRANSLATORS: 'preview image' = image that shows a preview of the full image */
 273       _("preview image"), _("preview image related to this stream"), NULL);
 274   gst_tag_register (GST_TAG_ATTACHMENT, GST_TAG_FLAG_META, GST_TYPE_SAMPLE,
 275       _("attachment"), _("file attached to this stream"),
 276       gst_tag_merge_use_first);
 277   gst_tag_register (GST_TAG_BEATS_PER_MINUTE, GST_TAG_FLAG_META, G_TYPE_DOUBLE,
 278       _("beats per minute"), _("number of beats per minute in audio"), NULL);
 279   gst_tag_register (GST_TAG_KEYWORDS, GST_TAG_FLAG_META, G_TYPE_STRING,
 280       _("keywords"), _("comma separated keywords describing the content"),
 281       gst_tag_merge_strings_with_comma);
 282   gst_tag_register (GST_TAG_GEO_LOCATION_NAME, GST_TAG_FLAG_META, G_TYPE_STRING,
 283       _("geo location name"), _("human readable descriptive location of where "
 284           "the media has been recorded or produced"), NULL);
 285   gst_tag_register (GST_TAG_GEO_LOCATION_LATITUDE, GST_TAG_FLAG_META,
 286       G_TYPE_DOUBLE, _("geo location latitude"),
 287       _("geo latitude location of where the media has been recorded or "
 288           "produced in degrees according to WGS84 (zero at the equator, "
 289           "negative values for southern latitudes)"), NULL);
 290   gst_tag_register (GST_TAG_GEO_LOCATION_LONGITUDE, GST_TAG_FLAG_META,
 291       G_TYPE_DOUBLE, _("geo location longitude"),
 292       _("geo longitude location of where the media has been recorded or "
 293           "produced in degrees according to WGS84 (zero at the prime meridian "
 294           "in Greenwich/UK,  negative values for western longitudes)"), NULL);
 295   gst_tag_register (GST_TAG_GEO_LOCATION_ELEVATION, GST_TAG_FLAG_META,
 296       G_TYPE_DOUBLE, _("geo location elevation"),
 297       _("geo elevation of where the media has been recorded or produced in "
 298           "meters according to WGS84 (zero is average sea level)"), NULL);
 299   gst_tag_register (GST_TAG_GEO_LOCATION_COUNTRY, GST_TAG_FLAG_META,
 300       G_TYPE_STRING, _("geo location country"),
 301       _("country (english name) where the media has been recorded "
 302           "or produced"), NULL);
 303   gst_tag_register (GST_TAG_GEO_LOCATION_CITY, GST_TAG_FLAG_META,
 304       G_TYPE_STRING, _("geo location city"),
 305       _("city (english name) where the media has been recorded "
 306           "or produced"), NULL);
 307   gst_tag_register (GST_TAG_GEO_LOCATION_SUBLOCATION, GST_TAG_FLAG_META,
 308       G_TYPE_STRING, _("geo location sublocation"),
 309       _("a location whithin a city where the media has been produced "
 310           "or created (e.g. the neighborhood)"), NULL);
 311   gst_tag_register (GST_TAG_GEO_LOCATION_HORIZONTAL_ERROR, GST_TAG_FLAG_META,
 312       G_TYPE_DOUBLE, _("geo location horizontal error"),
 313       _("expected error of the horizontal positioning measures (in meters)"),
 314       NULL);
 315   gst_tag_register (GST_TAG_GEO_LOCATION_MOVEMENT_SPEED, GST_TAG_FLAG_META,
 316       G_TYPE_DOUBLE, _("geo location movement speed"),
 317       _("movement speed of the capturing device while performing the capture "
 318           "in m/s"), NULL);
 319   gst_tag_register (GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION, GST_TAG_FLAG_META,
 320       G_TYPE_DOUBLE, _("geo location movement direction"),
 321       _("indicates the movement direction of the device performing the capture"
 322           " of a media. It is represented as degrees in floating point "
 323           "representation, 0 means the geographic north, and increases "
 324           "clockwise"), NULL);
 325   gst_tag_register (GST_TAG_GEO_LOCATION_CAPTURE_DIRECTION, GST_TAG_FLAG_META,
 326       G_TYPE_DOUBLE, _("geo location capture direction"),
 327       _("indicates the direction the device is pointing to when capturing "
 328           " a media. It is represented as degrees in floating point "
 329           " representation, 0 means the geographic north, and increases "
 330           "clockwise"), NULL);
 331   gst_tag_register (GST_TAG_SHOW_NAME, GST_TAG_FLAG_META, G_TYPE_STRING,
 332       /* TRANSLATORS: 'show name' = 'TV/radio/podcast show name' here */
 333       _("show name"),
 334       _("Name of the tv/podcast/series show the media is from"),
 335       gst_tag_merge_strings_with_comma);
 336   gst_tag_register (GST_TAG_SHOW_SORTNAME, GST_TAG_FLAG_META, G_TYPE_STRING,
 337       /* TRANSLATORS: 'show sortname' = 'TV/radio/podcast show name as used for sorting purposes' here */
 338       _("show sortname"),
 339       _("Name of the tv/podcast/series show the media is from, for sorting "
 340           "purposes"), NULL);
 341   gst_tag_register (GST_TAG_SHOW_EPISODE_NUMBER, GST_TAG_FLAG_META, G_TYPE_UINT,
 342       _("episode number"),
 343       _("The episode number in the season the media is part of"),
 344       gst_tag_merge_use_first);
 345   gst_tag_register (GST_TAG_SHOW_SEASON_NUMBER, GST_TAG_FLAG_META, G_TYPE_UINT,
 346       _("season number"),
 347       _("The season number of the show the media is part of"),
 348       gst_tag_merge_use_first);
 349   gst_tag_register (GST_TAG_LYRICS, GST_TAG_FLAG_META, G_TYPE_STRING,
 350       _("lyrics"), _("The lyrics of the media, commonly used for songs"),
 351       gst_tag_merge_strings_with_comma);
 352   gst_tag_register (GST_TAG_COMPOSER_SORTNAME, GST_TAG_FLAG_META, G_TYPE_STRING,
 353       _("composer sortname"),
 354       _("person(s) who composed the recording, for sorting purposes"), NULL);
 355   gst_tag_register (GST_TAG_GROUPING, GST_TAG_FLAG_META, G_TYPE_STRING,
 356       _("grouping"),
 357       _("Groups related media that spans multiple tracks, like the different "
 358           "pieces of a concerto. It is a higher level than a track, "
 359           "but lower than an album"), NULL);
 360   gst_tag_register (GST_TAG_USER_RATING, GST_TAG_FLAG_META, G_TYPE_UINT,
 361       _("user rating"),
 362       _("Rating attributed by a user. The higher the rank, "
 363           "the more the user likes this media"), NULL);
 364   gst_tag_register (GST_TAG_DEVICE_MANUFACTURER, GST_TAG_FLAG_META,
 365       G_TYPE_STRING, _("device manufacturer"),
 366       _("Manufacturer of the device used to create this media"), NULL);
 367   gst_tag_register (GST_TAG_DEVICE_MODEL, GST_TAG_FLAG_META, G_TYPE_STRING,
 368       _("device model"),
 369       _("Model of the device used to create this media"), NULL);
 370   gst_tag_register (GST_TAG_APPLICATION_NAME, GST_TAG_FLAG_META, G_TYPE_STRING,
 371       _("application name"), _("Application used to create the media"), NULL);
 372   gst_tag_register (GST_TAG_APPLICATION_DATA, GST_TAG_FLAG_META,
 373       GST_TYPE_BUFFER, _("application data"),
 374       _("Arbitrary application data to be serialized into the media"), NULL);
 375   gst_tag_register (GST_TAG_IMAGE_ORIENTATION, GST_TAG_FLAG_META, G_TYPE_STRING,
 376       _("image orientation"),
 377       _("How the image should be rotated or flipped before display"), NULL);
 378 }
 379
 380 /**
 381  * gst_tag_merge_use_first:
 382  * @dest: (out caller-allocates): uninitialized GValue to store result in
 383  * @src: GValue to copy from
 384  *
 385  * This is a convenience function for the func argument of gst_tag_register().
 386  * It creates a copy of the first value from the list.
 387  */
 388 void
 389 gst_tag_merge_use_first (GValue * dest, const GValue * src)
 390 {
 391   const GValue *ret = gst_value_list_get_value (src, 0);
 392
 393   g_value_init (dest, G_VALUE_TYPE (ret));
 394   g_value_copy (ret, dest);
 395 }
 396
 397 /**
 398  * gst_tag_merge_strings_with_comma:
 399  * @dest: (out caller-allocates): uninitialized GValue to store result in
 400  * @src: GValue to copy from
 401  *
 402  * This is a convenience function for the func argument of gst_tag_register().
 403  * It concatenates all given strings using a comma. The tag must be registered
 404  * as a G_TYPE_STRING or this function will fail.
 405  */
 406 void
 407 gst_tag_merge_strings_with_comma (GValue * dest, const GValue * src)
 408 {
 409   GString *str;
 410   gint i, count;
 411
 412   count = gst_value_list_get_size (src);
 413   str = g_string_new (g_value_get_string (gst_value_list_get_value (src, 0)));
 414   for (i = 1; i < count; i++) {
 415     /* separator between two strings */
 416     g_string_append (str, _(", "));
 417     g_string_append (str,
 418         g_value_get_string (gst_value_list_get_value (src, i)));
 419   }
 420
 421   g_value_init (dest, G_TYPE_STRING);
 422   g_value_take_string (dest, str->str);
 423   g_string_free (str, FALSE);
 424 }
 425
 426 static GstTagInfo *
 427 gst_tag_lookup (const gchar * tag_name)
 428 {
 429   GstTagInfo *ret;
 430
 431   TAG_LOCK;
 432   ret = g_hash_table_lookup (__tags, (gpointer) tag_name);
 433   TAG_UNLOCK;
 434
 435   return ret;
 436 }
 437
 438 /**
 439  * gst_tag_register:
 440  * @name: the name or identifier string
 441  * @flag: a flag describing the type of tag info
 442  * @type: the type this data is in
 443  * @nick: human-readable name
 444  * @blurb: a human-readable description about this tag
 445  * @func: function for merging multiple values of this tag, or NULL
 446  *
 447  * Registers a new tag type for the use with GStreamer's type system. If a type
 448  * with that name is already registered, that one is used.
 449  * The old registration may have used a different type however. So don't rely
 450  * on your supplied values.
 451  *
 452  * Important: if you do not supply a merge function the implication will be
 453  * that there can only be one single value for this tag in a tag list and
 454  * any additional values will silenty be discarded when being added (unless
 455  * #GST_TAG_MERGE_REPLACE, #GST_TAG_MERGE_REPLACE_ALL, or
 456  * #GST_TAG_MERGE_PREPEND is used as merge mode, in which case the new
 457  * value will replace the old one in the list).
 458  *
 459  * The merge function will be called from gst_tag_list_copy_value() when
 460  * it is required that one or more values for a tag be condensed into
 461  * one single value. This may happen from gst_tag_list_get_string(),
 462  * gst_tag_list_get_int(), gst_tag_list_get_double() etc. What will happen
 463  * exactly in that case depends on how the tag was registered and if a
 464  * merge function was supplied and if so which one.
 465  *
 466  * Two default merge functions are provided: gst_tag_merge_use_first() and
 467  * gst_tag_merge_strings_with_comma().
 468  */
 469 void
 470 gst_tag_register (const gchar * name, GstTagFlag flag, GType type,
 471     const gchar * nick, const gchar * blurb, GstTagMergeFunc func)
 472 {
 473   GstTagInfo *info;
 474   gchar *name_dup;
 475
 476   g_return_if_fail (name != NULL);
 477   g_return_if_fail (nick != NULL);
 478   g_return_if_fail (blurb != NULL);
 479   g_return_if_fail (type != 0 && type != GST_TYPE_LIST);
 480
 481   info = gst_tag_lookup (name);
 482
 483   if (info) {
 484     g_return_if_fail (info->type == type);
 485     return;
 486   }
 487
 488   info = g_slice_new (GstTagInfo);
 489   info->flag = flag;
 490   info->type = type;
 491   info->nick = g_strdup (nick);
 492   info->blurb = g_strdup (blurb);
 493   info->merge_func = func;
 494
 495   /* we make a copy for the hash table anyway, which will stay around, so
 496    * can use that for the quark table too */
 497   name_dup = g_strdup (name);
 498   info->name_quark = g_quark_from_static_string (name_dup);
 499
 500   TAG_LOCK;
 501   g_hash_table_insert (__tags, (gpointer) name_dup, info);
 502   TAG_UNLOCK;
 503 }
 504
 505 /**
 506  * gst_tag_exists:
 507  * @tag: name of the tag
 508  *
 509  * Checks if the given type is already registered.
 510  *
 511  * Returns: TRUE if the type is already registered
 512  */
 513 gboolean
 514 gst_tag_exists (const gchar * tag)
 515 {
 516   g_return_val_if_fail (tag != NULL, FALSE);
 517
 518   return gst_tag_lookup (tag) != NULL;
 519 }
 520
 521 /**
 522  * gst_tag_get_type:
 523  * @tag: the tag
 524  *
 525  * Gets the #GType used for this tag.
 526  *
 527  * Returns: the #GType of this tag
 528  */
 529 GType
 530 gst_tag_get_type (const gchar * tag)
 531 {
 532   GstTagInfo *info;
 533
 534   g_return_val_if_fail (tag != NULL, 0);
 535   info = gst_tag_lookup (tag);
 536   g_return_val_if_fail (info != NULL, 0);
 537
 538   return info->type;
 539 }
 540
 541 /**
 542  * gst_tag_get_nick
 543  * @tag: the tag
 544  *
 545  * Returns the human-readable name of this tag, You must not change or free
 546  * this string.
 547  *
 548  * Returns: the human-readable name of this tag
 549  */
 550 const gchar *
 551 gst_tag_get_nick (const gchar * tag)
 552 {
 553   GstTagInfo *info;
 554
 555   g_return_val_if_fail (tag != NULL, NULL);
 556   info = gst_tag_lookup (tag);
 557   g_return_val_if_fail (info != NULL, NULL);
 558
 559   return info->nick;
 560 }
 561
 562 /**
 563  * gst_tag_get_description:
 564  * @tag: the tag
 565  *
 566  * Returns the human-readable description of this tag, You must not change or
 567  * free this string.
 568  *
 569  * Returns: the human-readable description of this tag
 570  */
 571 const gchar *
 572 gst_tag_get_description (const gchar * tag)
 573 {
 574   GstTagInfo *info;
 575
 576   g_return_val_if_fail (tag != NULL, NULL);
 577   info = gst_tag_lookup (tag);
 578   g_return_val_if_fail (info != NULL, NULL);
 579
 580   return info->blurb;
 581 }
 582
 583 /**
 584  * gst_tag_get_flag:
 585  * @tag: the tag
 586  *
 587  * Gets the flag of @tag.
 588  *
 589  * Returns: the flag of this tag.
 590  */
 591 GstTagFlag
 592 gst_tag_get_flag (const gchar * tag)
 593 {
 594   GstTagInfo *info;
 595
 596   g_return_val_if_fail (tag != NULL, GST_TAG_FLAG_UNDEFINED);
 597   info = gst_tag_lookup (tag);
 598   g_return_val_if_fail (info != NULL, GST_TAG_FLAG_UNDEFINED);
 599
 600   return info->flag;
 601 }
 602
 603 /**
 604  * gst_tag_is_fixed:
 605  * @tag: tag to check
 606  *
 607  * Checks if the given tag is fixed. A fixed tag can only contain one value.
 608  * Unfixed tags can contain lists of values.
 609  *
 610  * Returns: TRUE, if the given tag is fixed.
 611  */
 612 gboolean
 613 gst_tag_is_fixed (const gchar * tag)
 614 {
 615   GstTagInfo *info;
 616
 617   g_return_val_if_fail (tag != NULL, FALSE);
 618   info = gst_tag_lookup (tag);
 619   g_return_val_if_fail (info != NULL, FALSE);
 620
 621   return info->merge_func == NULL;
 622 }
 623
 624 /**
 625  * gst_tag_list_new_empty:
 626  *
 627  * Creates a new empty GstTagList.
 628  *
 629  * Free-function: gst_tag_list_free
 630  *
 631  * Returns: (transfer full): An empty tag list
 632  */
 633 GstTagList *
 634 gst_tag_list_new_empty (void)
 635 {
 636   return GST_TAG_LIST (gst_structure_new_id_empty (GST_QUARK (TAGLIST)));
 637 }
 638
 639 /**
 640  * gst_tag_list_new:
 641  * @tag: tag
 642  * @...: NULL-terminated list of values to set
 643  *
 644  * Creates a new taglist and appends the values for the given tags. It expects
 645  * tag-value pairs like gst_tag_list_add(), and a NULL terminator after the
 646  * last pair. The type of the values is implicit and is documented in the API
 647  * reference, but can also be queried at runtime with gst_tag_get_type(). It
 648  * is an error to pass a value of a type not matching the tag type into this
 649  * function. The tag list will make copies of any arguments passed
 650  * (e.g. strings, buffers).
 651  *
 652  * Free-function: gst_tag_list_free
 653  *
 654  * Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_free()
 655  *     when no longer needed.
 656  *
 657  * Since: 0.10.24
 658  */
 659 GstTagList *
 660 gst_tag_list_new (const gchar * tag, ...)
 661 {
 662   GstTagList *list;
 663   va_list args;
 664
 665   g_return_val_if_fail (tag != NULL, NULL);
 666
 667   list = gst_tag_list_new_empty ();
 668   va_start (args, tag);
 669   gst_tag_list_add_valist (list, GST_TAG_MERGE_APPEND, tag, args);
 670   va_end (args);
 671
 672   return list;
 673 }
 674
 675 /**
 676  * gst_tag_list_new_valist:
 677  * @var_args: tag / value pairs to set
 678  *
 679  * Just like gst_tag_list_new(), only that it takes a va_list argument.
 680  * Useful mostly for language bindings.
 681  *
 682  * Free-function: gst_tag_list_free
 683  *
 684  * Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_free()
 685  *     when no longer needed.
 686  *
 687  * Since: 0.10.24
 688  */
 689 GstTagList *
 690 gst_tag_list_new_valist (va_list var_args)
 691 {
 692   GstTagList *list;
 693   const gchar *tag;
 694
 695   list = gst_tag_list_new_empty ();
 696
 697   tag = va_arg (var_args, gchar *);
 698   gst_tag_list_add_valist (list, GST_TAG_MERGE_APPEND, tag, var_args);
 699
 700   return list;
 701 }
 702
 703 /**
 704  * gst_tag_list_to_string:
 705  * @list: a #GstTagList
 706  *
 707  * Serializes a tag list to a string.
 708  *
 709  * Returns: a newly-allocated string, or NULL in case of an error. The
 710  *    string must be freed with g_free() when no longer needed.
 711  *
 712  * Since: 0.10.36
 713  */
 714 gchar *
 715 gst_tag_list_to_string (const GstTagList * list)
 716 {
 717   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
 718
 719   return gst_structure_to_string (GST_STRUCTURE (list));
 720 }
 721
 722 /**
 723  * gst_tag_list_new_from_string:
 724  * @str: a string created with gst_tag_list_to_string()
 725  *
 726  * Deserializes a tag list.
 727  *
 728  * Returns: a new #GstTagList, or NULL in case of an error.
 729  *
 730  * Since: 0.10.36
 731  */
 732 GstTagList *
 733 gst_tag_list_new_from_string (const gchar * str)
 734 {
 735   g_return_val_if_fail (str != NULL, NULL);
 736   g_return_val_if_fail (g_str_has_prefix (str, "taglist"), NULL);
 737
 738   return GST_TAG_LIST (gst_structure_from_string (str, NULL));
 739 }
 740
 741 /**
 742  * gst_tag_list_n_tags:
 743  * @list: A #GstTagList.
 744  *
 745  * Get the number of tags in @list.
 746  *
 747  * Returns: The number of tags in @list.
 748  */
 749 gint
 750 gst_tag_list_n_tags (const GstTagList * list)
 751 {
 752   g_return_val_if_fail (list != NULL, 0);
 753   g_return_val_if_fail (GST_IS_TAG_LIST (list), 0);
 754
 755   return gst_structure_n_fields ((GstStructure *) list);
 756 }
 757
 758 /**
 759  * gst_tag_list_nth_tag_name:
 760  * @list: A #GstTagList.
 761  * @index: the index
 762  *
 763  * Get the name of the tag in @list at @index.
 764  *
 765  * Returns: The name of the tag at @index.
 766  */
 767 const gchar *
 768 gst_tag_list_nth_tag_name (const GstTagList * list, guint index)
 769 {
 770   g_return_val_if_fail (list != NULL, 0);
 771   g_return_val_if_fail (GST_IS_TAG_LIST (list), 0);
 772
 773   return gst_structure_nth_field_name ((GstStructure *) list, index);
 774 }
 775
 776 /**
 777  * gst_tag_list_is_empty:
 778  * @list: A #GstTagList.
 779  *
 780  * Checks if the given taglist is empty.
 781  *
 782  * Returns: TRUE if the taglist is empty, otherwise FALSE.
 783  *
 784  * Since: 0.10.11
 785  */
 786 gboolean
 787 gst_tag_list_is_empty (const GstTagList * list)
 788 {
 789   g_return_val_if_fail (list != NULL, FALSE);
 790   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
 791
 792   return (gst_structure_n_fields ((GstStructure *) list) == 0);
 793 }
 794
 795 static gboolean
 796 gst_tag_list_fields_equal (const GValue * value1, const GValue * value2)
 797 {
 798   gdouble d1, d2;
 799
 800   if (gst_value_compare (value1, value2) == GST_VALUE_EQUAL)
 801     return TRUE;
 802
 803   /* fields not equal: add some tolerance for doubles, otherwise bail out */
 804   if (!G_VALUE_HOLDS_DOUBLE (value1) || !G_VALUE_HOLDS_DOUBLE (value2))
 805     return FALSE;
 806
 807   d1 = g_value_get_double (value1);
 808   d2 = g_value_get_double (value2);
 809
 810   /* This will only work for 'normal' values and values around 0,
 811    * which should be good enough for our purposes here
 812    * FIXME: maybe add this to gst_value_compare_double() ? */
 813   return (fabs (d1 - d2) < 0.0000001);
 814 }
 815
 816 /**
 817  * gst_tag_list_is_equal:
 818  * @list1: a #GstTagList.
 819  * @list2: a #GstTagList.
 820  *
 821  * Checks if the two given taglists are equal.
 822  *
 823  * Returns: TRUE if the taglists are equal, otherwise FALSE
 824  *
 825  * Since: 0.10.36
 826  */
 827 gboolean
 828 gst_tag_list_is_equal (const GstTagList * list1, const GstTagList * list2)
 829 {
 830   const GstStructure *s1, *s2;
 831   gint num_fields1, num_fields2, i;
 832
 833   g_return_val_if_fail (GST_IS_TAG_LIST (list1), FALSE);
 834   g_return_val_if_fail (GST_IS_TAG_LIST (list2), FALSE);
 835
 836   /* we don't just use gst_structure_is_equal() here so we can add some
 837    * tolerance for doubles, though maybe we should just add that to
 838    * gst_value_compare_double() as well? */
 839   s1 = (const GstStructure *) list1;
 840   s2 = (const GstStructure *) list2;
 841
 842   num_fields1 = gst_structure_n_fields (s1);
 843   num_fields2 = gst_structure_n_fields (s2);
 844
 845   if (num_fields1 != num_fields2)
 846     return FALSE;
 847
 848   for (i = 0; i < num_fields1; i++) {
 849     const GValue *value1, *value2;
 850     const gchar *tag_name;
 851
 852     tag_name = gst_structure_nth_field_name (s1, i);
 853     value1 = gst_structure_get_value (s1, tag_name);
 854     value2 = gst_structure_get_value (s2, tag_name);
 855
 856     if (value2 == NULL)
 857       return FALSE;
 858
 859     if (!gst_tag_list_fields_equal (value1, value2))
 860       return FALSE;
 861   }
 862
 863   return TRUE;
 864 }
 865
 866 /**
 867  * gst_is_tag_list:
 868  * @p: Object that might be a taglist
 869  *
 870  * Checks if the given pointer is a taglist.
 871  *
 872  * Returns: TRUE, if the given pointer is a taglist
 873  */
 874 gboolean
 875 gst_is_tag_list (gconstpointer p)
 876 {
 877   GstStructure *s = (GstStructure *) p;
 878
 879   g_return_val_if_fail (p != NULL, FALSE);
 880
 881   return (GST_IS_STRUCTURE (s) && s->name == GST_QUARK (TAGLIST));
 882 }
 883
 884 typedef struct
 885 {
 886   GstTagList *list;
 887   GstTagMergeMode mode;
 888 }
 889 GstTagCopyData;
 890
 891 static void
 892 gst_tag_list_add_value_internal (GstTagList * tag_list, GstTagMergeMode mode,
 893     const gchar * tag, const GValue * value, GstTagInfo * info)
 894 {
 895   GstStructure *list = GST_STRUCTURE (tag_list);
 896   const GValue *value2;
 897   GQuark tag_quark;
 898
 899   if (info == NULL) {
 900     info = gst_tag_lookup (tag);
 901     if (G_UNLIKELY (info == NULL)) {
 902       g_warning ("unknown tag '%s'", tag);
 903       return;
 904     }
 905   }
 906
 907   tag_quark = info->name_quark;
 908
 909   if (info->merge_func
 910       && (value2 = gst_structure_id_get_value (list, tag_quark)) != NULL) {
 911     GValue dest = { 0, };
 912
 913     switch (mode) {
 914       case GST_TAG_MERGE_REPLACE_ALL:
 915       case GST_TAG_MERGE_REPLACE:
 916         gst_structure_id_set_value (list, tag_quark, value);
 917         break;
 918       case GST_TAG_MERGE_PREPEND:
 919         gst_value_list_merge (&dest, value, value2);
 920         gst_structure_id_set_value (list, tag_quark, &dest);
 921         g_value_unset (&dest);
 922         break;
 923       case GST_TAG_MERGE_APPEND:
 924         gst_value_list_merge (&dest, value2, value);
 925         gst_structure_id_set_value (list, tag_quark, &dest);
 926         g_value_unset (&dest);
 927         break;
 928       case GST_TAG_MERGE_KEEP:
 929       case GST_TAG_MERGE_KEEP_ALL:
 930         break;
 931       default:
 932         g_assert_not_reached ();
 933         break;
 934     }
 935   } else {
 936     switch (mode) {
 937       case GST_TAG_MERGE_APPEND:
 938       case GST_TAG_MERGE_KEEP:
 939         if (gst_structure_id_get_value (list, tag_quark) != NULL)
 940           break;
 941         /* fall through */
 942       case GST_TAG_MERGE_REPLACE_ALL:
 943       case GST_TAG_MERGE_REPLACE:
 944       case GST_TAG_MERGE_PREPEND:
 945         gst_structure_id_set_value (list, tag_quark, value);
 946         break;
 947       case GST_TAG_MERGE_KEEP_ALL:
 948         break;
 949       default:
 950         g_assert_not_reached ();
 951         break;
 952     }
 953   }
 954 }
 955
 956 static gboolean
 957 gst_tag_list_copy_foreach (GQuark tag_quark, const GValue * value,
 958     gpointer user_data)
 959 {
 960   GstTagCopyData *copy = (GstTagCopyData *) user_data;
 961   const gchar *tag;
 962
 963   tag = g_quark_to_string (tag_quark);
 964   gst_tag_list_add_value_internal (copy->list, copy->mode, tag, value, NULL);
 965
 966   return TRUE;
 967 }
 968
 969 /**
 970  * gst_tag_list_insert:
 971  * @into: list to merge into
 972  * @from: list to merge from
 973  * @mode: the mode to use
 974  *
 975  * Inserts the tags of the @from list into the first list using the given mode.
 976  */
 977 void
 978 gst_tag_list_insert (GstTagList * into, const GstTagList * from,
 979     GstTagMergeMode mode)
 980 {
 981   GstTagCopyData data;
 982
 983   g_return_if_fail (GST_IS_TAG_LIST (into));
 984   g_return_if_fail (GST_IS_TAG_LIST (from));
 985   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
 986
 987   data.list = into;
 988   data.mode = mode;
 989   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
 990     gst_structure_remove_all_fields (GST_STRUCTURE (data.list));
 991   }
 992   gst_structure_foreach ((GstStructure *) from, gst_tag_list_copy_foreach,
 993       &data);
 994 }
 995
 996 /**
 997  * gst_tag_list_copy:
 998  * @list: list to copy
 999  *
1000  * Copies a given #GstTagList.
1001  *
1002  * Free-function: gst_tag_list_free
1003  *
1004  * Returns: (transfer full): copy of the given list
1005  */
1006 GstTagList *
1007 gst_tag_list_copy (const GstTagList * list)
1008 {
1009   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
1010
1011   return GST_TAG_LIST (gst_structure_copy ((GstStructure *) list));
1012 }
1013
1014 /**
1015  * gst_tag_list_merge:
1016  * @list1: first list to merge
1017  * @list2: second list to merge
1018  * @mode: the mode to use
1019  *
1020  * Merges the two given lists into a new list. If one of the lists is NULL, a
1021  * copy of the other is returned. If both lists are NULL, NULL is returned.
1022  *
1023  * Free-function: gst_tag_list_free
1024  *
1025  * Returns: (transfer full): the new list
1026  */
1027 GstTagList *
1028 gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2,
1029     GstTagMergeMode mode)
1030 {
1031   GstTagList *list1_cp;
1032   const GstTagList *list2_cp;
1033
1034   g_return_val_if_fail (list1 == NULL || GST_IS_TAG_LIST (list1), NULL);
1035   g_return_val_if_fail (list2 == NULL || GST_IS_TAG_LIST (list2), NULL);
1036   g_return_val_if_fail (GST_TAG_MODE_IS_VALID (mode), NULL);
1037
1038   /* nothing to merge */
1039   if (!list1 && !list2) {
1040     return NULL;
1041   }
1042
1043   /* create empty list, we need to do this to correctly handling merge modes */
1044   list1_cp = (list1) ? gst_tag_list_copy (list1) : gst_tag_list_new_empty ();
1045   list2_cp = (list2) ? list2 : gst_tag_list_new_empty ();
1046
1047   gst_tag_list_insert (list1_cp, list2_cp, mode);
1048
1049   if (!list2)
1050     gst_tag_list_free ((GstTagList *) list2_cp);
1051
1052   return list1_cp;
1053 }
1054
1055 /**
1056  * gst_tag_list_free:
1057  * @list: (in) (transfer full): the list to free
1058  *
1059  * Frees the given list and all associated values.
1060  */
1061 void
1062 gst_tag_list_free (GstTagList * list)
1063 {
1064   g_return_if_fail (GST_IS_TAG_LIST (list));
1065   gst_structure_free ((GstStructure *) list);
1066 }
1067
1068 /**
1069  * gst_tag_list_get_tag_size:
1070  * @list: a taglist
1071  * @tag: the tag to query
1072  *
1073  * Checks how many value are stored in this tag list for the given tag.
1074  *
1075  * Returns: The number of tags stored
1076  */
1077 guint
1078 gst_tag_list_get_tag_size (const GstTagList * list, const gchar * tag)
1079 {
1080   const GValue *value;
1081
1082   g_return_val_if_fail (GST_IS_TAG_LIST (list), 0);
1083
1084   value = gst_structure_get_value ((GstStructure *) list, tag);
1085   if (value == NULL)
1086     return 0;
1087   if (G_VALUE_TYPE (value) != GST_TYPE_LIST)
1088     return 1;
1089
1090   return gst_value_list_get_size (value);
1091 }
1092
1093 /**
1094  * gst_tag_list_add:
1095  * @list: list to set tags in
1096  * @mode: the mode to use
1097  * @tag: tag
1098  * @...: NULL-terminated list of values to set
1099  *
1100  * Sets the values for the given tags using the specified mode.
1101  */
1102 void
1103 gst_tag_list_add (GstTagList * list, GstTagMergeMode mode, const gchar * tag,
1104     ...)
1105 {
1106   va_list args;
1107
1108   g_return_if_fail (GST_IS_TAG_LIST (list));
1109   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1110   g_return_if_fail (tag != NULL);
1111
1112   va_start (args, tag);
1113   gst_tag_list_add_valist (list, mode, tag, args);
1114   va_end (args);
1115 }
1116
1117 /**
1118  * gst_tag_list_add_values:
1119  * @list: list to set tags in
1120  * @mode: the mode to use
1121  * @tag: tag
1122  * @...: GValues to set
1123  *
1124  * Sets the GValues for the given tags using the specified mode.
1125  */
1126 void
1127 gst_tag_list_add_values (GstTagList * list, GstTagMergeMode mode,
1128     const gchar * tag, ...)
1129 {
1130   va_list args;
1131
1132   g_return_if_fail (GST_IS_TAG_LIST (list));
1133   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1134   g_return_if_fail (tag != NULL);
1135
1136   va_start (args, tag);
1137   gst_tag_list_add_valist_values (list, mode, tag, args);
1138   va_end (args);
1139 }
1140
1141 /**
1142  * gst_tag_list_add_valist:
1143  * @list: list to set tags in
1144  * @mode: the mode to use
1145  * @tag: tag
1146  * @var_args: tag / value pairs to set
1147  *
1148  * Sets the values for the given tags using the specified mode.
1149  */
1150 void
1151 gst_tag_list_add_valist (GstTagList * list, GstTagMergeMode mode,
1152     const gchar * tag, va_list var_args)
1153 {
1154   GstTagInfo *info;
1155   gchar *error = NULL;
1156
1157   g_return_if_fail (GST_IS_TAG_LIST (list));
1158   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1159   g_return_if_fail (tag != NULL);
1160
1161   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
1162     gst_structure_remove_all_fields (GST_STRUCTURE (list));
1163   }
1164
1165   while (tag != NULL) {
1166     GValue value = { 0, };
1167
1168     info = gst_tag_lookup (tag);
1169     if (G_UNLIKELY (info == NULL)) {
1170       g_warning ("unknown tag '%s'", tag);
1171       return;
1172     }
1173     G_VALUE_COLLECT_INIT (&value, info->type, var_args, 0, &error);
1174     if (error) {
1175       g_warning ("%s: %s", G_STRLOC, error);
1176       g_free (error);
1177       /* we purposely leak the value here, it might not be
1178        * in a sane state if an error condition occoured
1179        */
1180       return;
1181     }
1182     gst_tag_list_add_value_internal (list, mode, tag, &value, info);
1183     g_value_unset (&value);
1184     tag = va_arg (var_args, gchar *);
1185   }
1186 }
1187
1188 /**
1189  * gst_tag_list_add_valist_values:
1190  * @list: list to set tags in
1191  * @mode: the mode to use
1192  * @tag: tag
1193  * @var_args: tag / GValue pairs to set
1194  *
1195  * Sets the GValues for the given tags using the specified mode.
1196  */
1197 void
1198 gst_tag_list_add_valist_values (GstTagList * list, GstTagMergeMode mode,
1199     const gchar * tag, va_list var_args)
1200 {
1201   g_return_if_fail (GST_IS_TAG_LIST (list));
1202   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1203   g_return_if_fail (tag != NULL);
1204
1205   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
1206     gst_structure_remove_all_fields (GST_STRUCTURE (list));
1207   }
1208
1209   while (tag != NULL) {
1210     GstTagInfo *info;
1211
1212     info = gst_tag_lookup (tag);
1213     if (G_UNLIKELY (info == NULL)) {
1214       g_warning ("unknown tag '%s'", tag);
1215       return;
1216     }
1217     gst_tag_list_add_value_internal (list, mode, tag, va_arg (var_args,
1218             GValue *), info);
1219     tag = va_arg (var_args, gchar *);
1220   }
1221 }
1222
1223 /**
1224  * gst_tag_list_add_value:
1225  * @list: list to set tags in
1226  * @mode: the mode to use
1227  * @tag: tag
1228  * @value: GValue for this tag
1229  *
1230  * Sets the GValue for a given tag using the specified mode.
1231  *
1232  * Since: 0.10.24
1233  */
1234 void
1235 gst_tag_list_add_value (GstTagList * list, GstTagMergeMode mode,
1236     const gchar * tag, const GValue * value)
1237 {
1238   g_return_if_fail (GST_IS_TAG_LIST (list));
1239   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1240   g_return_if_fail (tag != NULL);
1241
1242   gst_tag_list_add_value_internal (list, mode, tag, value, NULL);
1243 }
1244
1245 /**
1246  * gst_tag_list_remove_tag:
1247  * @list: list to remove tag from
1248  * @tag: tag to remove
1249  *
1250  * Removes the given tag from the taglist.
1251  */
1252 void
1253 gst_tag_list_remove_tag (GstTagList * list, const gchar * tag)
1254 {
1255   g_return_if_fail (GST_IS_TAG_LIST (list));
1256   g_return_if_fail (tag != NULL);
1257
1258   gst_structure_remove_field ((GstStructure *) list, tag);
1259 }
1260
1261 typedef struct
1262 {
1263   GstTagForeachFunc func;
1264   const GstTagList *tag_list;
1265   gpointer data;
1266 }
1267 TagForeachData;
1268
1269 static int
1270 structure_foreach_wrapper (GQuark field_id, const GValue * value,
1271     gpointer user_data)
1272 {
1273   TagForeachData *data = (TagForeachData *) user_data;
1274
1275   data->func (data->tag_list, g_quark_to_string (field_id), data->data);
1276   return TRUE;
1277 }
1278
1279 /**
1280  * gst_tag_list_foreach:
1281  * @list: list to iterate over
1282  * @func: (scope call): function to be called for each tag
1283  * @user_data: (closure): user specified data
1284  *
1285  * Calls the given function for each tag inside the tag list. Note that if there
1286  * is no tag, the function won't be called at all.
1287  */
1288 void
1289 gst_tag_list_foreach (const GstTagList * list, GstTagForeachFunc func,
1290     gpointer user_data)
1291 {
1292   TagForeachData data;
1293
1294   g_return_if_fail (GST_IS_TAG_LIST (list));
1295   g_return_if_fail (func != NULL);
1296
1297   data.func = func;
1298   data.tag_list = list;
1299   data.data = user_data;
1300   gst_structure_foreach ((GstStructure *) list, structure_foreach_wrapper,
1301       &data);
1302 }
1303
1304 /**
1305  * gst_tag_list_get_value_index:
1306  * @list: a #GstTagList
1307  * @tag: tag to read out
1308  * @index: number of entry to read out
1309  *
1310  * Gets the value that is at the given index for the given tag in the given
1311  * list.
1312  *
1313  * Returns: (transfer none): The GValue for the specified entry or NULL if the
1314  *          tag wasn't available or the tag doesn't have as many entries
1315  */
1316 const GValue *
1317 gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag,
1318     guint index)
1319 {
1320   const GValue *value;
1321
1322   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
1323   g_return_val_if_fail (tag != NULL, NULL);
1324
1325   value = gst_structure_get_value ((GstStructure *) list, tag);
1326   if (value == NULL)
1327     return NULL;
1328
1329   if (GST_VALUE_HOLDS_LIST (value)) {
1330     if (index >= gst_value_list_get_size (value))
1331       return NULL;
1332     return gst_value_list_get_value (value, index);
1333   } else {
1334     if (index > 0)
1335       return NULL;
1336     return value;
1337   }
1338 }
1339
1340 /**
1341  * gst_tag_list_copy_value:
1342  * @dest: (out caller-allocates): uninitialized #GValue to copy into
1343  * @list: list to get the tag from
1344  * @tag: tag to read out
1345  *
1346  * Copies the contents for the given tag into the value,
1347  * merging multiple values into one if multiple values are associated
1348  * with the tag.
1349  * You must g_value_unset() the value after use.
1350  *
1351  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1352  *          given list.
1353  */
1354 gboolean
1355 gst_tag_list_copy_value (GValue * dest, const GstTagList * list,
1356     const gchar * tag)
1357 {
1358   const GValue *src;
1359
1360   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1361   g_return_val_if_fail (tag != NULL, FALSE);
1362   g_return_val_if_fail (dest != NULL, FALSE);
1363   g_return_val_if_fail (G_VALUE_TYPE (dest) == 0, FALSE);
1364
1365   src = gst_structure_get_value ((GstStructure *) list, tag);
1366   if (!src)
1367     return FALSE;
1368
1369   if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
1370     GstTagInfo *info = gst_tag_lookup (tag);
1371
1372     if (!info)
1373       return FALSE;
1374
1375     /* must be there or lists aren't allowed */
1376     g_assert (info->merge_func);
1377     info->merge_func (dest, src);
1378   } else {
1379     g_value_init (dest, G_VALUE_TYPE (src));
1380     g_value_copy (src, dest);
1381   }
1382   return TRUE;
1383 }
1384
1385 /* FIXME 0.11: this whole merge function business is overdesigned, and the
1386  * _get_foo() API is misleading as well - how many application developers will
1387  * expect gst_tag_list_get_string (list, GST_TAG_ARTIST, &val) might return a
1388  * string with multiple comma-separated artists? _get_foo() should just be
1389  * a convenience wrapper around _get_foo_index (list, tag, 0, &val),
1390  * supplemented by a special _tag_list_get_string_merged() function if needed
1391  * (unless someone can actually think of real use cases where the merge
1392  * function is not 'use first' for non-strings and merge for strings) */
1393
1394 /***** evil macros to get all the gst_tag_list_get_*() functions right *****/
1395
1396 #define TAG_MERGE_FUNCS(name,type,ret)                                  \
1397 gboolean                                                                \
1398 gst_tag_list_get_ ## name (const GstTagList *list, const gchar *tag,    \
1399                            type *value)                                 \
1400 {                                                                       \
1401   GValue v = { 0, };                                                    \
1402                                                                         \
1403   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                 \
1404   g_return_val_if_fail (tag != NULL, FALSE);                            \
1405   g_return_val_if_fail (value != NULL, FALSE);                          \
1406                                                                         \
1407   if (!gst_tag_list_copy_value (&v, list, tag))                         \
1408       return FALSE;                                                     \
1409   *value = COPY_FUNC (g_value_get_ ## name (&v));                       \
1410   g_value_unset (&v);                                                   \
1411   return ret;                                                           \
1412 }                                                                       \
1413                                                                         \
1414 gboolean                                                                \
1415 gst_tag_list_get_ ## name ## _index (const GstTagList *list,            \
1416                                      const gchar *tag,                  \
1417                                      guint index, type *value)          \
1418 {                                                                       \
1419   const GValue *v;                                                      \
1420                                                                         \
1421   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                 \
1422   g_return_val_if_fail (tag != NULL, FALSE);                            \
1423   g_return_val_if_fail (value != NULL, FALSE);                          \
1424                                                                         \
1425   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)    \
1426       return FALSE;                                                     \
1427   *value = COPY_FUNC (g_value_get_ ## name (v));                        \
1428   return ret;                                                           \
1429 }
1430
1431 #define COPY_FUNC /**/
1432 /**
1433  * gst_tag_list_get_boolean:
1434  * @list: a #GstTagList to get the tag from
1435  * @tag: tag to read out
1436  * @value: (out): location for the result
1437  *
1438  * Copies the contents for the given tag into the value, merging multiple values
1439  * into one if multiple values are associated with the tag.
1440  *
1441  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1442  *              given list.
1443  */
1444 /**
1445  * gst_tag_list_get_boolean_index:
1446  * @list: a #GstTagList to get the tag from
1447  * @tag: tag to read out
1448  * @index: number of entry to read out
1449  * @value: (out): location for the result
1450  *
1451  * Gets the value that is at the given index for the given tag in the given
1452  * list.
1453  *
1454  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1455  *              given list.
1456  */
1457 TAG_MERGE_FUNCS (boolean, gboolean, TRUE);
1458 /**
1459  * gst_tag_list_get_int:
1460  * @list: a #GstTagList to get the tag from
1461  * @tag: tag to read out
1462  * @value: (out): location for the result
1463  *
1464  * Copies the contents for the given tag into the value, merging multiple values
1465  * into one if multiple values are associated with the tag.
1466  *
1467  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1468  *              given list.
1469  */
1470 /**
1471  * gst_tag_list_get_int_index:
1472  * @list: a #GstTagList to get the tag from
1473  * @tag: tag to read out
1474  * @index: number of entry to read out
1475  * @value: (out): location for the result
1476  *
1477  * Gets the value that is at the given index for the given tag in the given
1478  * list.
1479  *
1480  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1481  *              given list.
1482  */
1483 TAG_MERGE_FUNCS (int, gint, TRUE);
1484 /**
1485  * gst_tag_list_get_uint:
1486  * @list: a #GstTagList to get the tag from
1487  * @tag: tag to read out
1488  * @value: (out): location for the result
1489  *
1490  * Copies the contents for the given tag into the value, merging multiple values
1491  * into one if multiple values are associated with the tag.
1492  *
1493  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1494  *              given list.
1495  */
1496 /**
1497  * gst_tag_list_get_uint_index:
1498  * @list: a #GstTagList to get the tag from
1499  * @tag: tag to read out
1500  * @index: number of entry to read out
1501  * @value: (out): location for the result
1502  *
1503  * Gets the value that is at the given index for the given tag in the given
1504  * list.
1505  *
1506  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1507  *              given list.
1508  */
1509 TAG_MERGE_FUNCS (uint, guint, TRUE);
1510 /**
1511  * gst_tag_list_get_int64_index:
1512  * @list: a #GstTagList to get the tag from
1513  * @tag: tag to read out
1514  * @index: number of entry to read out
1515  * @value: (out): location for the result
1516  *
1517  * Gets the value that is at the given index for the given tag in the given
1518  * list.
1519  *
1520  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1521  *              given list.
1522  */
1523 TAG_MERGE_FUNCS (int64, gint64, TRUE);
1524 /**
1525  * gst_tag_list_get_uint64:
1526  * @list: a #GstTagList to get the tag from
1527  * @tag: tag to read out
1528  * @value: (out): location for the result
1529  *
1530  * Copies the contents for the given tag into the value, merging multiple values
1531  * into one if multiple values are associated with the tag.
1532  *
1533  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1534  *              given list.
1535  */
1536 /**
1537  * gst_tag_list_get_uint64_index:
1538  * @list: a #GstTagList to get the tag from
1539  * @tag: tag to read out
1540  * @index: number of entry to read out
1541  * @value: (out): location for the result
1542  *
1543  * Gets the value that is at the given index for the given tag in the given
1544  * list.
1545  *
1546  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1547  *              given list.
1548  */
1549 TAG_MERGE_FUNCS (uint64, guint64, TRUE);
1550 /**
1551  * gst_tag_list_get_float:
1552  * @list: a #GstTagList to get the tag from
1553  * @tag: tag to read out
1554  * @value: (out): location for the result
1555  *
1556  * Copies the contents for the given tag into the value, merging multiple values
1557  * into one if multiple values are associated with the tag.
1558  *
1559  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1560  *              given list.
1561  */
1562 /**
1563  * gst_tag_list_get_float_index:
1564  * @list: a #GstTagList to get the tag from
1565  * @tag: tag to read out
1566  * @index: number of entry to read out
1567  * @value: (out): location for the result
1568  *
1569  * Gets the value that is at the given index for the given tag in the given
1570  * list.
1571  *
1572  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1573  *              given list.
1574  */
1575 TAG_MERGE_FUNCS (float, gfloat, TRUE);
1576 /**
1577  * gst_tag_list_get_double:
1578  * @list: a #GstTagList to get the tag from
1579  * @tag: tag to read out
1580  * @value: (out): location for the result
1581  *
1582  * Copies the contents for the given tag into the value, merging multiple values
1583  * into one if multiple values are associated with the tag.
1584  *
1585  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1586  *              given list.
1587  */
1588 /**
1589  * gst_tag_list_get_double_index:
1590  * @list: a #GstTagList to get the tag from
1591  * @tag: tag to read out
1592  * @index: number of entry to read out
1593  * @value: (out): location for the result
1594  *
1595  * Gets the value that is at the given index for the given tag in the given
1596  * list.
1597  *
1598  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1599  *              given list.
1600  */
1601 TAG_MERGE_FUNCS (double, gdouble, TRUE);
1602 /**
1603  * gst_tag_list_get_pointer:
1604  * @list: a #GstTagList to get the tag from
1605  * @tag: tag to read out
1606  * @value: (out) (transfer none): location for the result
1607  *
1608  * Copies the contents for the given tag into the value, merging multiple values
1609  * into one if multiple values are associated with the tag.
1610  *
1611  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1612  *              given list.
1613  */
1614 /**
1615  * gst_tag_list_get_pointer_index:
1616  * @list: a #GstTagList to get the tag from
1617  * @tag: tag to read out
1618  * @index: number of entry to read out
1619  * @value: (out) (transfer none): location for the result
1620  *
1621  * Gets the value that is at the given index for the given tag in the given
1622  * list.
1623  *
1624  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1625  *              given list.
1626  */
1627 TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL));
1628
1629 static inline gchar *
1630 _gst_strdup0 (const gchar * s)
1631 {
1632   if (s == NULL || *s == '\0')
1633     return NULL;
1634
1635   return g_strdup (s);
1636 }
1637
1638 #undef COPY_FUNC
1639 #define COPY_FUNC _gst_strdup0
1640
1641 /**
1642  * gst_tag_list_get_string:
1643  * @list: a #GstTagList to get the tag from
1644  * @tag: tag to read out
1645  * @value: (out callee-allocates) (transfer full): location for the result
1646  *
1647  * Copies the contents for the given tag into the value, possibly merging
1648  * multiple values into one if multiple values are associated with the tag.
1649  *
1650  * Use gst_tag_list_get_string_index (list, tag, 0, value) if you want
1651  * to retrieve the first string associated with this tag unmodified.
1652  *
1653  * The resulting string in @value will be in UTF-8 encoding and should be
1654  * freed by the caller using g_free when no longer needed. Since 0.10.24 the
1655  * returned string is also guaranteed to be non-NULL and non-empty.
1656  *
1657  * Free-function: g_free
1658  *
1659  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1660  *              given list.
1661  */
1662 /**
1663  * gst_tag_list_get_string_index:
1664  * @list: a #GstTagList to get the tag from
1665  * @tag: tag to read out
1666  * @index: number of entry to read out
1667  * @value: (out callee-allocates) (transfer full): location for the result
1668  *
1669  * Gets the value that is at the given index for the given tag in the given
1670  * list.
1671  *
1672  * The resulting string in @value will be in UTF-8 encoding and should be
1673  * freed by the caller using g_free when no longer needed. Since 0.10.24 the
1674  * returned string is also guaranteed to be non-NULL and non-empty.
1675  *
1676  * Free-function: g_free
1677  *
1678  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1679  *              given list.
1680  */
1681 TAG_MERGE_FUNCS (string, gchar *, (*value != NULL));
1682
1683 /*
1684  *FIXME 0.11: Instead of _peek (non-copy) and _get (copy), we could have
1685  *            _get (non-copy) and _dup (copy) for strings, seems more
1686  *            widely used
1687  */
1688 /**
1689  * gst_tag_list_peek_string_index:
1690  * @list: a #GstTagList to get the tag from
1691  * @tag: tag to read out
1692  * @index: number of entry to read out
1693  * @value: (out) (transfer none): location for the result
1694  *
1695  * Peeks at the value that is at the given index for the given tag in the given
1696  * list.
1697  *
1698  * The resulting string in @value will be in UTF-8 encoding and doesn't need
1699  * to be freed by the caller. The returned string is also guaranteed to
1700  * be non-NULL and non-empty.
1701  *
1702  * Returns: TRUE, if a value was set, FALSE if the tag didn't exist in the
1703  *              given list.
1704  */
1705 gboolean
1706 gst_tag_list_peek_string_index (const GstTagList * list,
1707     const gchar * tag, guint index, const gchar ** value)
1708 {
1709   const GValue *v;
1710
1711   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1712   g_return_val_if_fail (tag != NULL, FALSE);
1713   g_return_val_if_fail (value != NULL, FALSE);
1714
1715   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1716     return FALSE;
1717   *value = g_value_get_string (v);
1718   return *value != NULL && **value != '\0';
1719 }
1720
1721 /**
1722  * gst_tag_list_get_date:
1723  * @list: a #GstTagList to get the tag from
1724  * @tag: tag to read out
1725  * @value: (out callee-allocates) (transfer full): address of a GDate pointer
1726  *     variable to store the result into
1727  *
1728  * Copies the first date for the given tag in the taglist into the variable
1729  * pointed to by @value. Free the date with g_date_free() when it is no longer
1730  * needed.
1731  *
1732  * Free-function: g_date_free
1733  *
1734  * Returns: TRUE, if a date was copied, FALSE if the tag didn't exist in the
1735  *              given list or if it was #NULL.
1736  */
1737 gboolean
1738 gst_tag_list_get_date (const GstTagList * list, const gchar * tag,
1739     GDate ** value)
1740 {
1741   GValue v = { 0, };
1742
1743   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1744   g_return_val_if_fail (tag != NULL, FALSE);
1745   g_return_val_if_fail (value != NULL, FALSE);
1746
1747   if (!gst_tag_list_copy_value (&v, list, tag))
1748     return FALSE;
1749   *value = (GDate *) g_value_dup_boxed (&v);
1750   g_value_unset (&v);
1751   return (*value != NULL);
1752 }
1753
1754 /**
1755  * gst_tag_list_get_date_index:
1756  * @list: a #GstTagList to get the tag from
1757  * @tag: tag to read out
1758  * @index: number of entry to read out
1759  * @value: (out callee-allocates) (transfer full): location for the result
1760  *
1761  * Gets the date that is at the given index for the given tag in the given
1762  * list and copies it into the variable pointed to by @value. Free the date
1763  * with g_date_free() when it is no longer needed.
1764  *
1765  * Free-function: g_date_free
1766  *
1767  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1768  *              given list or if it was #NULL.
1769  */
1770 gboolean
1771 gst_tag_list_get_date_index (const GstTagList * list,
1772     const gchar * tag, guint index, GDate ** value)
1773 {
1774   const GValue *v;
1775
1776   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1777   g_return_val_if_fail (tag != NULL, FALSE);
1778   g_return_val_if_fail (value != NULL, FALSE);
1779
1780   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1781     return FALSE;
1782   *value = (GDate *) g_value_dup_boxed (v);
1783   return (*value != NULL);
1784 }
1785
1786 /**
1787  * gst_tag_list_get_date_time:
1788  * @list: a #GstTagList to get the tag from
1789  * @tag: tag to read out
1790  * @value: (out callee-allocates) (transfer full): address of a #GstDateTime
1791  *     pointer variable to store the result into
1792  *
1793  * Copies the first datetime for the given tag in the taglist into the variable
1794  * pointed to by @value. Unref the date with gst_date_time_unref() when
1795  * it is no longer needed.
1796  *
1797  * Free-function: gst_date_time_unref
1798  *
1799  * Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in
1800  *              thegiven list or if it was #NULL.
1801  *
1802  * Since: 0.10.31
1803  */
1804 gboolean
1805 gst_tag_list_get_date_time (const GstTagList * list, const gchar * tag,
1806     GstDateTime ** value)
1807 {
1808   GValue v = { 0, };
1809
1810   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1811   g_return_val_if_fail (tag != NULL, FALSE);
1812   g_return_val_if_fail (value != NULL, FALSE);
1813
1814   if (!gst_tag_list_copy_value (&v, list, tag))
1815     return FALSE;
1816
1817   g_return_val_if_fail (GST_VALUE_HOLDS_DATE_TIME (&v), FALSE);
1818
1819   *value = (GstDateTime *) g_value_dup_boxed (&v);
1820   g_value_unset (&v);
1821   return (*value != NULL);
1822 }
1823
1824 /**
1825  * gst_tag_list_get_date_time_index:
1826  * @list: a #GstTagList to get the tag from
1827  * @tag: tag to read out
1828  * @index: number of entry to read out
1829  * @value: (out callee-allocates) (transfer full): location for the result
1830  *
1831  * Gets the datetime that is at the given index for the given tag in the given
1832  * list and copies it into the variable pointed to by @value. Unref the datetime
1833  * with gst_date_time_unref() when it is no longer needed.
1834  *
1835  * Free-function: gst_date_time_unref
1836  *
1837  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1838  *              given list or if it was #NULL.
1839  *
1840  * Since: 0.10.31
1841  */
1842 gboolean
1843 gst_tag_list_get_date_time_index (const GstTagList * list,
1844     const gchar * tag, guint index, GstDateTime ** value)
1845 {
1846   const GValue *v;
1847
1848   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1849   g_return_val_if_fail (tag != NULL, FALSE);
1850   g_return_val_if_fail (value != NULL, FALSE);
1851
1852   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1853     return FALSE;
1854   *value = (GstDateTime *) g_value_dup_boxed (v);
1855   return (*value != NULL);
1856 }
1857
1858 /**
1859  * gst_tag_list_get_buffer:
1860  * @list: a #GstTagList to get the tag from
1861  * @tag: tag to read out
1862  * @value: (out callee-allocates) (transfer full): address of a GstBuffer
1863  *     pointer variable to store the result into
1864  *
1865  * Copies the first buffer for the given tag in the taglist into the variable
1866  * pointed to by @value. Free the buffer with gst_buffer_unref() when it is
1867  * no longer needed.
1868  *
1869  * Free-function: gst_buffer_unref
1870  *
1871  * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
1872  *              given list or if it was #NULL.
1873  *
1874  * Since: 0.10.23
1875  */
1876 gboolean
1877 gst_tag_list_get_buffer (const GstTagList * list, const gchar * tag,
1878     GstBuffer ** value)
1879 {
1880   GValue v = { 0, };
1881
1882   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1883   g_return_val_if_fail (tag != NULL, FALSE);
1884   g_return_val_if_fail (value != NULL, FALSE);
1885
1886   if (!gst_tag_list_copy_value (&v, list, tag))
1887     return FALSE;
1888   *value = g_value_dup_boxed (&v);
1889   g_value_unset (&v);
1890   return (*value != NULL);
1891 }
1892
1893 /**
1894  * gst_tag_list_get_buffer_index:
1895  * @list: a #GstTagList to get the tag from
1896  * @tag: tag to read out
1897  * @index: number of entry to read out
1898  * @value: (out callee-allocates) (transfer full): address of a GstBuffer
1899  *     pointer variable to store the result into
1900  *
1901  * Gets the buffer that is at the given index for the given tag in the given
1902  * list and copies it into the variable pointed to by @value. Free the buffer
1903  * with gst_buffer_unref() when it is no longer needed.
1904  *
1905  * Free-function: gst_buffer_unref
1906  *
1907  * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
1908  *              given list or if it was #NULL.
1909  *
1910  * Since: 0.10.23
1911  */
1912 gboolean
1913 gst_tag_list_get_buffer_index (const GstTagList * list,
1914     const gchar * tag, guint index, GstBuffer ** value)
1915 {
1916   const GValue *v;
1917
1918   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1919   g_return_val_if_fail (tag != NULL, FALSE);
1920   g_return_val_if_fail (value != NULL, FALSE);
1921
1922   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1923     return FALSE;
1924   *value = g_value_dup_boxed (v);
1925   return (*value != NULL);
1926 }