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