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_BUFFER,
 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_BUFFER,
 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_BUFFER,
 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 /* FIXME 0.11: maybe get rid of _get_char*(), _get_uchar*(), _get_long*(),
1401  * _get_ulong*() and _get_pointer*()? - they are not really useful/common
1402  * enough to warrant convenience accessor functions */
1403
1404 #define COPY_FUNC /**/
1405 /**
1406  * gst_tag_list_get_char:
1407  * @list: a #GstTagList to get the tag from
1408  * @tag: tag to read out
1409  * @value: (out): location for the result
1410  *
1411  * Copies the contents for the given tag into the value, merging multiple values
1412  * into one if multiple values are associated with the tag.
1413  *
1414  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1415  *              given list.
1416  */
1417 /**
1418  * gst_tag_list_get_char_index:
1419  * @list: a #GstTagList to get the tag from
1420  * @tag: tag to read out
1421  * @index: number of entry to read out
1422  * @value: (out): location for the result
1423  *
1424  * Gets the value that is at the given index for the given tag in the given
1425  * list.
1426  *
1427  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1428  *              given list.
1429  */
1430 TAG_MERGE_FUNCS (char, gchar, TRUE);
1431 /**
1432  * gst_tag_list_get_uchar:
1433  * @list: a #GstTagList to get the tag from
1434  * @tag: tag to read out
1435  * @value: (out): location for the result
1436  *
1437  * Copies the contents for the given tag into the value, merging multiple values
1438  * into one if multiple values are associated with the tag.
1439  *
1440  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1441  *              given list.
1442  */
1443 /**
1444  * gst_tag_list_get_uchar_index:
1445  * @list: a #GstTagList to get the tag from
1446  * @tag: tag to read out
1447  * @index: number of entry to read out
1448  * @value: (out): location for the result
1449  *
1450  * Gets the value that is at the given index for the given tag in the given
1451  * list.
1452  *
1453  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1454  *              given list.
1455  */
1456 TAG_MERGE_FUNCS (uchar, guchar, TRUE);
1457 /**
1458  * gst_tag_list_get_boolean:
1459  * @list: a #GstTagList to get the tag from
1460  * @tag: tag to read out
1461  * @value: (out): location for the result
1462  *
1463  * Copies the contents for the given tag into the value, merging multiple values
1464  * into one if multiple values are associated with the tag.
1465  *
1466  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1467  *              given list.
1468  */
1469 /**
1470  * gst_tag_list_get_boolean_index:
1471  * @list: a #GstTagList to get the tag from
1472  * @tag: tag to read out
1473  * @index: number of entry to read out
1474  * @value: (out): location for the result
1475  *
1476  * Gets the value that is at the given index for the given tag in the given
1477  * list.
1478  *
1479  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1480  *              given list.
1481  */
1482 TAG_MERGE_FUNCS (boolean, gboolean, TRUE);
1483 /**
1484  * gst_tag_list_get_int:
1485  * @list: a #GstTagList to get the tag from
1486  * @tag: tag to read out
1487  * @value: (out): location for the result
1488  *
1489  * Copies the contents for the given tag into the value, merging multiple values
1490  * into one if multiple values are associated with the tag.
1491  *
1492  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1493  *              given list.
1494  */
1495 /**
1496  * gst_tag_list_get_int_index:
1497  * @list: a #GstTagList to get the tag from
1498  * @tag: tag to read out
1499  * @index: number of entry to read out
1500  * @value: (out): location for the result
1501  *
1502  * Gets the value that is at the given index for the given tag in the given
1503  * list.
1504  *
1505  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1506  *              given list.
1507  */
1508 TAG_MERGE_FUNCS (int, gint, TRUE);
1509 /**
1510  * gst_tag_list_get_uint:
1511  * @list: a #GstTagList to get the tag from
1512  * @tag: tag to read out
1513  * @value: (out): location for the result
1514  *
1515  * Copies the contents for the given tag into the value, merging multiple values
1516  * into one if multiple values are associated with the tag.
1517  *
1518  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1519  *              given list.
1520  */
1521 /**
1522  * gst_tag_list_get_uint_index:
1523  * @list: a #GstTagList to get the tag from
1524  * @tag: tag to read out
1525  * @index: number of entry to read out
1526  * @value: (out): location for the result
1527  *
1528  * Gets the value that is at the given index for the given tag in the given
1529  * list.
1530  *
1531  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1532  *              given list.
1533  */
1534 TAG_MERGE_FUNCS (uint, guint, TRUE);
1535 /**
1536  * gst_tag_list_get_int64_index:
1537  * @list: a #GstTagList to get the tag from
1538  * @tag: tag to read out
1539  * @index: number of entry to read out
1540  * @value: (out): location for the result
1541  *
1542  * Gets the value that is at the given index for the given tag in the given
1543  * list.
1544  *
1545  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1546  *              given list.
1547  */
1548 TAG_MERGE_FUNCS (int64, gint64, TRUE);
1549 /**
1550  * gst_tag_list_get_uint64:
1551  * @list: a #GstTagList to get the tag from
1552  * @tag: tag to read out
1553  * @value: (out): location for the result
1554  *
1555  * Copies the contents for the given tag into the value, merging multiple values
1556  * into one if multiple values are associated with the tag.
1557  *
1558  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1559  *              given list.
1560  */
1561 /**
1562  * gst_tag_list_get_uint64_index:
1563  * @list: a #GstTagList to get the tag from
1564  * @tag: tag to read out
1565  * @index: number of entry to read out
1566  * @value: (out): location for the result
1567  *
1568  * Gets the value that is at the given index for the given tag in the given
1569  * list.
1570  *
1571  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1572  *              given list.
1573  */
1574 TAG_MERGE_FUNCS (uint64, guint64, TRUE);
1575 /**
1576  * gst_tag_list_get_float:
1577  * @list: a #GstTagList to get the tag from
1578  * @tag: tag to read out
1579  * @value: (out): location for the result
1580  *
1581  * Copies the contents for the given tag into the value, merging multiple values
1582  * into one if multiple values are associated with the tag.
1583  *
1584  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1585  *              given list.
1586  */
1587 /**
1588  * gst_tag_list_get_float_index:
1589  * @list: a #GstTagList to get the tag from
1590  * @tag: tag to read out
1591  * @index: number of entry to read out
1592  * @value: (out): location for the result
1593  *
1594  * Gets the value that is at the given index for the given tag in the given
1595  * list.
1596  *
1597  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1598  *              given list.
1599  */
1600 TAG_MERGE_FUNCS (float, gfloat, TRUE);
1601 /**
1602  * gst_tag_list_get_double:
1603  * @list: a #GstTagList to get the tag from
1604  * @tag: tag to read out
1605  * @value: (out): location for the result
1606  *
1607  * Copies the contents for the given tag into the value, merging multiple values
1608  * into one if multiple values are associated with the tag.
1609  *
1610  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1611  *              given list.
1612  */
1613 /**
1614  * gst_tag_list_get_double_index:
1615  * @list: a #GstTagList to get the tag from
1616  * @tag: tag to read out
1617  * @index: number of entry to read out
1618  * @value: (out): location for the result
1619  *
1620  * Gets the value that is at the given index for the given tag in the given
1621  * list.
1622  *
1623  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1624  *              given list.
1625  */
1626 TAG_MERGE_FUNCS (double, gdouble, TRUE);
1627 /**
1628  * gst_tag_list_get_pointer:
1629  * @list: a #GstTagList to get the tag from
1630  * @tag: tag to read out
1631  * @value: (out) (transfer none): location for the result
1632  *
1633  * Copies the contents for the given tag into the value, merging multiple values
1634  * into one if multiple values are associated with the tag.
1635  *
1636  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1637  *              given list.
1638  */
1639 /**
1640  * gst_tag_list_get_pointer_index:
1641  * @list: a #GstTagList to get the tag from
1642  * @tag: tag to read out
1643  * @index: number of entry to read out
1644  * @value: (out) (transfer none): location for the result
1645  *
1646  * Gets the value that is at the given index for the given tag in the given
1647  * list.
1648  *
1649  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1650  *              given list.
1651  */
1652 TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL));
1653
1654 static inline gchar *
1655 _gst_strdup0 (const gchar * s)
1656 {
1657   if (s == NULL || *s == '\0')
1658     return NULL;
1659
1660   return g_strdup (s);
1661 }
1662
1663 #undef COPY_FUNC
1664 #define COPY_FUNC _gst_strdup0
1665
1666 /**
1667  * gst_tag_list_get_string:
1668  * @list: a #GstTagList to get the tag from
1669  * @tag: tag to read out
1670  * @value: (out callee-allocates) (transfer full): location for the result
1671  *
1672  * Copies the contents for the given tag into the value, possibly merging
1673  * multiple values into one if multiple values are associated with the tag.
1674  *
1675  * Use gst_tag_list_get_string_index (list, tag, 0, value) if you want
1676  * to retrieve the first string associated with this tag unmodified.
1677  *
1678  * The resulting string in @value will be in UTF-8 encoding and should be
1679  * freed by the caller using g_free when no longer needed. Since 0.10.24 the
1680  * returned string is also guaranteed to be non-NULL and non-empty.
1681  *
1682  * Free-function: g_free
1683  *
1684  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1685  *              given list.
1686  */
1687 /**
1688  * gst_tag_list_get_string_index:
1689  * @list: a #GstTagList to get the tag from
1690  * @tag: tag to read out
1691  * @index: number of entry to read out
1692  * @value: (out callee-allocates) (transfer full): location for the result
1693  *
1694  * Gets the value that is at the given index for the given tag in the given
1695  * list.
1696  *
1697  * The resulting string in @value will be in UTF-8 encoding and should be
1698  * freed by the caller using g_free when no longer needed. Since 0.10.24 the
1699  * returned string is also guaranteed to be non-NULL and non-empty.
1700  *
1701  * Free-function: g_free
1702  *
1703  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1704  *              given list.
1705  */
1706 TAG_MERGE_FUNCS (string, gchar *, (*value != NULL));
1707
1708 /*
1709  *FIXME 0.11: Instead of _peek (non-copy) and _get (copy), we could have
1710  *            _get (non-copy) and _dup (copy) for strings, seems more
1711  *            widely used
1712  */
1713 /**
1714  * gst_tag_list_peek_string_index:
1715  * @list: a #GstTagList to get the tag from
1716  * @tag: tag to read out
1717  * @index: number of entry to read out
1718  * @value: (out) (transfer none): location for the result
1719  *
1720  * Peeks at the value that is at the given index for the given tag in the given
1721  * list.
1722  *
1723  * The resulting string in @value will be in UTF-8 encoding and doesn't need
1724  * to be freed by the caller. The returned string is also guaranteed to
1725  * be non-NULL and non-empty.
1726  *
1727  * Returns: TRUE, if a value was set, FALSE if the tag didn't exist in the
1728  *              given list.
1729  */
1730 gboolean
1731 gst_tag_list_peek_string_index (const GstTagList * list,
1732     const gchar * tag, guint index, const gchar ** value)
1733 {
1734   const GValue *v;
1735
1736   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1737   g_return_val_if_fail (tag != NULL, FALSE);
1738   g_return_val_if_fail (value != NULL, FALSE);
1739
1740   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1741     return FALSE;
1742   *value = g_value_get_string (v);
1743   return *value != NULL && **value != '\0';
1744 }
1745
1746 /**
1747  * gst_tag_list_get_date:
1748  * @list: a #GstTagList to get the tag from
1749  * @tag: tag to read out
1750  * @value: (out callee-allocates) (transfer full): address of a GDate pointer
1751  *     variable to store the result into
1752  *
1753  * Copies the first date for the given tag in the taglist into the variable
1754  * pointed to by @value. Free the date with g_date_free() when it is no longer
1755  * needed.
1756  *
1757  * Free-function: g_date_free
1758  *
1759  * Returns: TRUE, if a date was copied, FALSE if the tag didn't exist in the
1760  *              given list or if it was #NULL.
1761  */
1762 gboolean
1763 gst_tag_list_get_date (const GstTagList * list, const gchar * tag,
1764     GDate ** value)
1765 {
1766   GValue v = { 0, };
1767
1768   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1769   g_return_val_if_fail (tag != NULL, FALSE);
1770   g_return_val_if_fail (value != NULL, FALSE);
1771
1772   if (!gst_tag_list_copy_value (&v, list, tag))
1773     return FALSE;
1774   *value = (GDate *) g_value_dup_boxed (&v);
1775   g_value_unset (&v);
1776   return (*value != NULL);
1777 }
1778
1779 /**
1780  * gst_tag_list_get_date_index:
1781  * @list: a #GstTagList to get the tag from
1782  * @tag: tag to read out
1783  * @index: number of entry to read out
1784  * @value: (out callee-allocates) (transfer full): location for the result
1785  *
1786  * Gets the date that is at the given index for the given tag in the given
1787  * list and copies it into the variable pointed to by @value. Free the date
1788  * with g_date_free() when it is no longer needed.
1789  *
1790  * Free-function: g_date_free
1791  *
1792  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1793  *              given list or if it was #NULL.
1794  */
1795 gboolean
1796 gst_tag_list_get_date_index (const GstTagList * list,
1797     const gchar * tag, guint index, GDate ** value)
1798 {
1799   const GValue *v;
1800
1801   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1802   g_return_val_if_fail (tag != NULL, FALSE);
1803   g_return_val_if_fail (value != NULL, FALSE);
1804
1805   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1806     return FALSE;
1807   *value = (GDate *) g_value_dup_boxed (v);
1808   return (*value != NULL);
1809 }
1810
1811 /**
1812  * gst_tag_list_get_date_time:
1813  * @list: a #GstTagList to get the tag from
1814  * @tag: tag to read out
1815  * @value: (out callee-allocates) (transfer full): address of a #GstDateTime
1816  *     pointer variable to store the result into
1817  *
1818  * Copies the first datetime for the given tag in the taglist into the variable
1819  * pointed to by @value. Unref the date with gst_date_time_unref() when
1820  * it is no longer needed.
1821  *
1822  * Free-function: gst_date_time_unref
1823  *
1824  * Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in
1825  *              thegiven list or if it was #NULL.
1826  *
1827  * Since: 0.10.31
1828  */
1829 gboolean
1830 gst_tag_list_get_date_time (const GstTagList * list, const gchar * tag,
1831     GstDateTime ** value)
1832 {
1833   GValue v = { 0, };
1834
1835   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1836   g_return_val_if_fail (tag != NULL, FALSE);
1837   g_return_val_if_fail (value != NULL, FALSE);
1838
1839   if (!gst_tag_list_copy_value (&v, list, tag))
1840     return FALSE;
1841
1842   g_return_val_if_fail (GST_VALUE_HOLDS_DATE_TIME (&v), FALSE);
1843
1844   *value = (GstDateTime *) g_value_dup_boxed (&v);
1845   g_value_unset (&v);
1846   return (*value != NULL);
1847 }
1848
1849 /**
1850  * gst_tag_list_get_date_time_index:
1851  * @list: a #GstTagList to get the tag from
1852  * @tag: tag to read out
1853  * @index: number of entry to read out
1854  * @value: (out callee-allocates) (transfer full): location for the result
1855  *
1856  * Gets the datetime that is at the given index for the given tag in the given
1857  * list and copies it into the variable pointed to by @value. Unref the datetime
1858  * with gst_date_time_unref() when it is no longer needed.
1859  *
1860  * Free-function: gst_date_time_unref
1861  *
1862  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1863  *              given list or if it was #NULL.
1864  *
1865  * Since: 0.10.31
1866  */
1867 gboolean
1868 gst_tag_list_get_date_time_index (const GstTagList * list,
1869     const gchar * tag, guint index, GstDateTime ** value)
1870 {
1871   const GValue *v;
1872
1873   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1874   g_return_val_if_fail (tag != NULL, FALSE);
1875   g_return_val_if_fail (value != NULL, FALSE);
1876
1877   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1878     return FALSE;
1879   *value = (GstDateTime *) g_value_dup_boxed (v);
1880   return (*value != NULL);
1881 }
1882
1883 /**
1884  * gst_tag_list_get_buffer:
1885  * @list: a #GstTagList to get the tag from
1886  * @tag: tag to read out
1887  * @value: (out callee-allocates) (transfer full): address of a GstBuffer
1888  *     pointer variable to store the result into
1889  *
1890  * Copies the first buffer for the given tag in the taglist into the variable
1891  * pointed to by @value. Free the buffer with gst_buffer_unref() when it is
1892  * no longer needed.
1893  *
1894  * Free-function: gst_buffer_unref
1895  *
1896  * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
1897  *              given list or if it was #NULL.
1898  *
1899  * Since: 0.10.23
1900  */
1901 gboolean
1902 gst_tag_list_get_buffer (const GstTagList * list, const gchar * tag,
1903     GstBuffer ** value)
1904 {
1905   GValue v = { 0, };
1906
1907   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1908   g_return_val_if_fail (tag != NULL, FALSE);
1909   g_return_val_if_fail (value != NULL, FALSE);
1910
1911   if (!gst_tag_list_copy_value (&v, list, tag))
1912     return FALSE;
1913   *value = g_value_dup_boxed (&v);
1914   g_value_unset (&v);
1915   return (*value != NULL);
1916 }
1917
1918 /**
1919  * gst_tag_list_get_buffer_index:
1920  * @list: a #GstTagList to get the tag from
1921  * @tag: tag to read out
1922  * @index: number of entry to read out
1923  * @value: (out callee-allocates) (transfer full): address of a GstBuffer
1924  *     pointer variable to store the result into
1925  *
1926  * Gets the buffer that is at the given index for the given tag in the given
1927  * list and copies it into the variable pointed to by @value. Free the buffer
1928  * with gst_buffer_unref() when it is no longer needed.
1929  *
1930  * Free-function: gst_buffer_unref
1931  *
1932  * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
1933  *              given list or if it was #NULL.
1934  *
1935  * Since: 0.10.23
1936  */
1937 gboolean
1938 gst_tag_list_get_buffer_index (const GstTagList * list,
1939     const gchar * tag, guint index, GstBuffer ** value)
1940 {
1941   const GValue *v;
1942
1943   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1944   g_return_val_if_fail (tag != NULL, FALSE);
1945   g_return_val_if_fail (value != NULL, FALSE);
1946
1947   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1948     return FALSE;
1949   *value = g_value_dup_boxed (v);
1950   return (*value != NULL);
1951 }