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