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:
 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 (void)
 639 {
 640   return GST_TAG_LIST (gst_structure_id_empty_new (GST_QUARK (TAGLIST)));
 641 }
 642
 643 /**
 644  * gst_tag_list_new_full:
 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 /* FIXME 0.11: rename gst_tag_list_new_full to _new and _new to _new_empty */
 664 GstTagList *
 665 gst_tag_list_new_full (const gchar * tag, ...)
 666 {
 667   GstTagList *list;
 668   va_list args;
 669
 670   g_return_val_if_fail (tag != NULL, NULL);
 671
 672   list = gst_tag_list_new ();
 673   va_start (args, tag);
 674   gst_tag_list_add_valist (list, GST_TAG_MERGE_APPEND, tag, args);
 675   va_end (args);
 676
 677   return list;
 678 }
 679
 680 /**
 681  * gst_tag_list_new_full_valist:
 682  * @var_args: tag / value pairs to set
 683  *
 684  * Just like gst_tag_list_new_full(), only that it takes a va_list argument.
 685  * Useful mostly for language bindings.
 686  *
 687  * Free-function: gst_tag_list_free
 688  *
 689  * Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_free()
 690  *     when no longer needed.
 691  *
 692  * Since: 0.10.24
 693  */
 694 GstTagList *
 695 gst_tag_list_new_full_valist (va_list var_args)
 696 {
 697   GstTagList *list;
 698   const gchar *tag;
 699
 700   list = gst_tag_list_new ();
 701
 702   tag = va_arg (var_args, gchar *);
 703   gst_tag_list_add_valist (list, GST_TAG_MERGE_APPEND, tag, var_args);
 704
 705   return list;
 706 }
 707
 708 /**
 709  * gst_tag_list_to_string:
 710  * @list: a #GstTagList
 711  *
 712  * Serializes a tag list to a string.
 713  *
 714  * Returns: a newly-allocated string, or NULL in case of an error. The
 715  *    string must be freed with g_free() when no longer needed.
 716  *
 717  * Since: 0.10.36
 718  */
 719 gchar *
 720 gst_tag_list_to_string (const GstTagList * list)
 721 {
 722   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
 723
 724   return gst_structure_to_string (GST_STRUCTURE (list));
 725 }
 726
 727 /**
 728  * gst_tag_list_new_from_string:
 729  * @str: a string created with gst_tag_list_to_string()
 730  *
 731  * Deserializes a tag list.
 732  *
 733  * Returns: a new #GstTagList, or NULL in case of an error.
 734  *
 735  * Since: 0.10.36
 736  */
 737 GstTagList *
 738 gst_tag_list_new_from_string (const gchar * str)
 739 {
 740   g_return_val_if_fail (str != NULL, NULL);
 741   g_return_val_if_fail (g_str_has_prefix (str, "taglist"), NULL);
 742
 743   return GST_TAG_LIST (gst_structure_from_string (str, NULL));
 744 }
 745
 746 /**
 747  * gst_tag_list_is_empty:
 748  * @list: A #GstTagList.
 749  *
 750  * Checks if the given taglist is empty.
 751  *
 752  * Returns: TRUE if the taglist is empty, otherwise FALSE.
 753  *
 754  * Since: 0.10.11
 755  */
 756 gboolean
 757 gst_tag_list_is_empty (const GstTagList * list)
 758 {
 759   g_return_val_if_fail (list != NULL, FALSE);
 760   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
 761
 762   return (gst_structure_n_fields ((GstStructure *) list) == 0);
 763 }
 764
 765 static gboolean
 766 gst_tag_list_fields_equal (const GValue * value1, const GValue * value2)
 767 {
 768   gdouble d1, d2;
 769
 770   if (gst_value_compare (value1, value2) == GST_VALUE_EQUAL)
 771     return TRUE;
 772
 773   /* fields not equal: add some tolerance for doubles, otherwise bail out */
 774   if (!G_VALUE_HOLDS_DOUBLE (value1) || !G_VALUE_HOLDS_DOUBLE (value2))
 775     return FALSE;
 776
 777   d1 = g_value_get_double (value1);
 778   d2 = g_value_get_double (value2);
 779
 780   /* This will only work for 'normal' values and values around 0,
 781    * which should be good enough for our purposes here
 782    * FIXME: maybe add this to gst_value_compare_double() ? */
 783   return (fabs (d1 - d2) < 0.0000001);
 784 }
 785
 786 /**
 787  * gst_tag_list_is_equal:
 788  * @list1: a #GstTagList.
 789  * @list2: a #GstTagList.
 790  *
 791  * Checks if the two given taglists are equal.
 792  *
 793  * Returns: TRUE if the taglists are equal, otherwise FALSE
 794  *
 795  * Since: 0.10.36
 796  */
 797 gboolean
 798 gst_tag_list_is_equal (const GstTagList * list1, const GstTagList * list2)
 799 {
 800   const GstStructure *s1, *s2;
 801   gint num_fields1, num_fields2, i;
 802
 803   g_return_val_if_fail (GST_IS_TAG_LIST (list1), FALSE);
 804   g_return_val_if_fail (GST_IS_TAG_LIST (list2), FALSE);
 805
 806   /* we don't just use gst_structure_is_equal() here so we can add some
 807    * tolerance for doubles, though maybe we should just add that to
 808    * gst_value_compare_double() as well? */
 809   s1 = (const GstStructure *) list1;
 810   s2 = (const GstStructure *) list2;
 811
 812   num_fields1 = gst_structure_n_fields (s1);
 813   num_fields2 = gst_structure_n_fields (s2);
 814
 815   if (num_fields1 != num_fields2)
 816     return FALSE;
 817
 818   for (i = 0; i < num_fields1; i++) {
 819     const GValue *value1, *value2;
 820     const gchar *tag_name;
 821
 822     tag_name = gst_structure_nth_field_name (s1, i);
 823     value1 = gst_structure_get_value (s1, tag_name);
 824     value2 = gst_structure_get_value (s2, tag_name);
 825
 826     if (value2 == NULL)
 827       return FALSE;
 828
 829     if (!gst_tag_list_fields_equal (value1, value2))
 830       return FALSE;
 831   }
 832
 833   return TRUE;
 834 }
 835
 836 /**
 837  * gst_is_tag_list:
 838  * @p: Object that might be a taglist
 839  *
 840  * Checks if the given pointer is a taglist.
 841  *
 842  * Returns: TRUE, if the given pointer is a taglist
 843  */
 844 gboolean
 845 gst_is_tag_list (gconstpointer p)
 846 {
 847   GstStructure *s = (GstStructure *) p;
 848
 849   g_return_val_if_fail (p != NULL, FALSE);
 850
 851   return (GST_IS_STRUCTURE (s) && s->name == GST_QUARK (TAGLIST));
 852 }
 853
 854 typedef struct
 855 {
 856   GstTagList *list;
 857   GstTagMergeMode mode;
 858 }
 859 GstTagCopyData;
 860
 861 static void
 862 gst_tag_list_add_value_internal (GstTagList * tag_list, GstTagMergeMode mode,
 863     const gchar * tag, const GValue * value, GstTagInfo * info)
 864 {
 865   GstStructure *list = GST_STRUCTURE (tag_list);
 866   const GValue *value2;
 867   GQuark tag_quark;
 868
 869   if (info == NULL) {
 870     info = gst_tag_lookup (tag);
 871     if (G_UNLIKELY (info == NULL)) {
 872       g_warning ("unknown tag '%s'", tag);
 873       return;
 874     }
 875   }
 876
 877   tag_quark = info->name_quark;
 878
 879   if (info->merge_func
 880       && (value2 = gst_structure_id_get_value (list, tag_quark)) != NULL) {
 881     GValue dest = { 0, };
 882
 883     switch (mode) {
 884       case GST_TAG_MERGE_REPLACE_ALL:
 885       case GST_TAG_MERGE_REPLACE:
 886         gst_structure_id_set_value (list, tag_quark, value);
 887         break;
 888       case GST_TAG_MERGE_PREPEND:
 889         gst_value_list_merge (&dest, value, value2);
 890         gst_structure_id_set_value (list, tag_quark, &dest);
 891         g_value_unset (&dest);
 892         break;
 893       case GST_TAG_MERGE_APPEND:
 894         gst_value_list_merge (&dest, value2, value);
 895         gst_structure_id_set_value (list, tag_quark, &dest);
 896         g_value_unset (&dest);
 897         break;
 898       case GST_TAG_MERGE_KEEP:
 899       case GST_TAG_MERGE_KEEP_ALL:
 900         break;
 901       default:
 902         g_assert_not_reached ();
 903         break;
 904     }
 905   } else {
 906     switch (mode) {
 907       case GST_TAG_MERGE_APPEND:
 908       case GST_TAG_MERGE_KEEP:
 909         if (gst_structure_id_get_value (list, tag_quark) != NULL)
 910           break;
 911         /* fall through */
 912       case GST_TAG_MERGE_REPLACE_ALL:
 913       case GST_TAG_MERGE_REPLACE:
 914       case GST_TAG_MERGE_PREPEND:
 915         gst_structure_id_set_value (list, tag_quark, value);
 916         break;
 917       case GST_TAG_MERGE_KEEP_ALL:
 918         break;
 919       default:
 920         g_assert_not_reached ();
 921         break;
 922     }
 923   }
 924 }
 925
 926 static gboolean
 927 gst_tag_list_copy_foreach (GQuark tag_quark, const GValue * value,
 928     gpointer user_data)
 929 {
 930   GstTagCopyData *copy = (GstTagCopyData *) user_data;
 931   const gchar *tag;
 932
 933   tag = g_quark_to_string (tag_quark);
 934   gst_tag_list_add_value_internal (copy->list, copy->mode, tag, value, NULL);
 935
 936   return TRUE;
 937 }
 938
 939 /**
 940  * gst_tag_list_insert:
 941  * @into: list to merge into
 942  * @from: list to merge from
 943  * @mode: the mode to use
 944  *
 945  * Inserts the tags of the @from list into the first list using the given mode.
 946  */
 947 void
 948 gst_tag_list_insert (GstTagList * into, const GstTagList * from,
 949     GstTagMergeMode mode)
 950 {
 951   GstTagCopyData data;
 952
 953   g_return_if_fail (GST_IS_TAG_LIST (into));
 954   g_return_if_fail (GST_IS_TAG_LIST (from));
 955   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
 956
 957   data.list = into;
 958   data.mode = mode;
 959   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
 960     gst_structure_remove_all_fields (GST_STRUCTURE (data.list));
 961   }
 962   gst_structure_foreach ((GstStructure *) from, gst_tag_list_copy_foreach,
 963       &data);
 964 }
 965
 966 /**
 967  * gst_tag_list_copy:
 968  * @list: list to copy
 969  *
 970  * Copies a given #GstTagList.
 971  *
 972  * Free-function: gst_tag_list_free
 973  *
 974  * Returns: (transfer full): copy of the given list
 975  */
 976 GstTagList *
 977 gst_tag_list_copy (const GstTagList * list)
 978 {
 979   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
 980
 981   return GST_TAG_LIST (gst_structure_copy ((GstStructure *) list));
 982 }
 983
 984 /**
 985  * gst_tag_list_merge:
 986  * @list1: first list to merge
 987  * @list2: second list to merge
 988  * @mode: the mode to use
 989  *
 990  * Merges the two given lists into a new list. If one of the lists is NULL, a
 991  * copy of the other is returned. If both lists are NULL, NULL is returned.
 992  *
 993  * Free-function: gst_tag_list_free
 994  *
 995  * Returns: (transfer full): the new list
 996  */
 997 GstTagList *
 998 gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2,
 999     GstTagMergeMode mode)
1000 {
1001   GstTagList *list1_cp;
1002   const GstTagList *list2_cp;
1003
1004   g_return_val_if_fail (list1 == NULL || GST_IS_TAG_LIST (list1), NULL);
1005   g_return_val_if_fail (list2 == NULL || GST_IS_TAG_LIST (list2), NULL);
1006   g_return_val_if_fail (GST_TAG_MODE_IS_VALID (mode), NULL);
1007
1008   /* nothing to merge */
1009   if (!list1 && !list2) {
1010     return NULL;
1011   }
1012
1013   /* create empty list, we need to do this to correctly handling merge modes */
1014   list1_cp = (list1) ? gst_tag_list_copy (list1) : gst_tag_list_new ();
1015   list2_cp = (list2) ? list2 : gst_tag_list_new ();
1016
1017   gst_tag_list_insert (list1_cp, list2_cp, mode);
1018
1019   if (!list2)
1020     gst_tag_list_free ((GstTagList *) list2_cp);
1021
1022   return list1_cp;
1023 }
1024
1025 /**
1026  * gst_tag_list_free:
1027  * @list: (in) (transfer full): the list to free
1028  *
1029  * Frees the given list and all associated values.
1030  */
1031 void
1032 gst_tag_list_free (GstTagList * list)
1033 {
1034   g_return_if_fail (GST_IS_TAG_LIST (list));
1035   gst_structure_free ((GstStructure *) list);
1036 }
1037
1038 /**
1039  * gst_tag_list_get_tag_size:
1040  * @list: a taglist
1041  * @tag: the tag to query
1042  *
1043  * Checks how many value are stored in this tag list for the given tag.
1044  *
1045  * Returns: The number of tags stored
1046  */
1047 guint
1048 gst_tag_list_get_tag_size (const GstTagList * list, const gchar * tag)
1049 {
1050   const GValue *value;
1051
1052   g_return_val_if_fail (GST_IS_TAG_LIST (list), 0);
1053
1054   value = gst_structure_get_value ((GstStructure *) list, tag);
1055   if (value == NULL)
1056     return 0;
1057   if (G_VALUE_TYPE (value) != GST_TYPE_LIST)
1058     return 1;
1059
1060   return gst_value_list_get_size (value);
1061 }
1062
1063 /**
1064  * gst_tag_list_add:
1065  * @list: list to set tags in
1066  * @mode: the mode to use
1067  * @tag: tag
1068  * @...: NULL-terminated list of values to set
1069  *
1070  * Sets the values for the given tags using the specified mode.
1071  */
1072 void
1073 gst_tag_list_add (GstTagList * list, GstTagMergeMode mode, const gchar * tag,
1074     ...)
1075 {
1076   va_list args;
1077
1078   g_return_if_fail (GST_IS_TAG_LIST (list));
1079   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1080   g_return_if_fail (tag != NULL);
1081
1082   va_start (args, tag);
1083   gst_tag_list_add_valist (list, mode, tag, args);
1084   va_end (args);
1085 }
1086
1087 /**
1088  * gst_tag_list_add_values:
1089  * @list: list to set tags in
1090  * @mode: the mode to use
1091  * @tag: tag
1092  * @...: GValues to set
1093  *
1094  * Sets the GValues for the given tags using the specified mode.
1095  */
1096 void
1097 gst_tag_list_add_values (GstTagList * list, GstTagMergeMode mode,
1098     const gchar * tag, ...)
1099 {
1100   va_list args;
1101
1102   g_return_if_fail (GST_IS_TAG_LIST (list));
1103   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1104   g_return_if_fail (tag != NULL);
1105
1106   va_start (args, tag);
1107   gst_tag_list_add_valist_values (list, mode, tag, args);
1108   va_end (args);
1109 }
1110
1111 /**
1112  * gst_tag_list_add_valist:
1113  * @list: list to set tags in
1114  * @mode: the mode to use
1115  * @tag: tag
1116  * @var_args: tag / value pairs to set
1117  *
1118  * Sets the values for the given tags using the specified mode.
1119  */
1120 void
1121 gst_tag_list_add_valist (GstTagList * list, GstTagMergeMode mode,
1122     const gchar * tag, va_list var_args)
1123 {
1124   GstTagInfo *info;
1125   gchar *error = NULL;
1126
1127   g_return_if_fail (GST_IS_TAG_LIST (list));
1128   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1129   g_return_if_fail (tag != NULL);
1130
1131   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
1132     gst_structure_remove_all_fields (GST_STRUCTURE (list));
1133   }
1134
1135   while (tag != NULL) {
1136     GValue value = { 0, };
1137
1138     info = gst_tag_lookup (tag);
1139     if (G_UNLIKELY (info == NULL)) {
1140       g_warning ("unknown tag '%s'", tag);
1141       return;
1142     }
1143     G_VALUE_COLLECT_INIT (&value, info->type, var_args, 0, &error);
1144     if (error) {
1145       g_warning ("%s: %s", G_STRLOC, error);
1146       g_free (error);
1147       /* we purposely leak the value here, it might not be
1148        * in a sane state if an error condition occoured
1149        */
1150       return;
1151     }
1152     gst_tag_list_add_value_internal (list, mode, tag, &value, info);
1153     g_value_unset (&value);
1154     tag = va_arg (var_args, gchar *);
1155   }
1156 }
1157
1158 /**
1159  * gst_tag_list_add_valist_values:
1160  * @list: list to set tags in
1161  * @mode: the mode to use
1162  * @tag: tag
1163  * @var_args: tag / GValue pairs to set
1164  *
1165  * Sets the GValues for the given tags using the specified mode.
1166  */
1167 void
1168 gst_tag_list_add_valist_values (GstTagList * list, GstTagMergeMode mode,
1169     const gchar * tag, va_list var_args)
1170 {
1171   g_return_if_fail (GST_IS_TAG_LIST (list));
1172   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1173   g_return_if_fail (tag != NULL);
1174
1175   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
1176     gst_structure_remove_all_fields (GST_STRUCTURE (list));
1177   }
1178
1179   while (tag != NULL) {
1180     GstTagInfo *info;
1181
1182     info = gst_tag_lookup (tag);
1183     if (G_UNLIKELY (info == NULL)) {
1184       g_warning ("unknown tag '%s'", tag);
1185       return;
1186     }
1187     gst_tag_list_add_value_internal (list, mode, tag, va_arg (var_args,
1188             GValue *), info);
1189     tag = va_arg (var_args, gchar *);
1190   }
1191 }
1192
1193 /**
1194  * gst_tag_list_add_value:
1195  * @list: list to set tags in
1196  * @mode: the mode to use
1197  * @tag: tag
1198  * @value: GValue for this tag
1199  *
1200  * Sets the GValue for a given tag using the specified mode.
1201  *
1202  * Since: 0.10.24
1203  */
1204 void
1205 gst_tag_list_add_value (GstTagList * list, GstTagMergeMode mode,
1206     const gchar * tag, const GValue * value)
1207 {
1208   g_return_if_fail (GST_IS_TAG_LIST (list));
1209   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
1210   g_return_if_fail (tag != NULL);
1211
1212   gst_tag_list_add_value_internal (list, mode, tag, value, NULL);
1213 }
1214
1215 /**
1216  * gst_tag_list_remove_tag:
1217  * @list: list to remove tag from
1218  * @tag: tag to remove
1219  *
1220  * Removes the given tag from the taglist.
1221  */
1222 void
1223 gst_tag_list_remove_tag (GstTagList * list, const gchar * tag)
1224 {
1225   g_return_if_fail (GST_IS_TAG_LIST (list));
1226   g_return_if_fail (tag != NULL);
1227
1228   gst_structure_remove_field ((GstStructure *) list, tag);
1229 }
1230
1231 typedef struct
1232 {
1233   GstTagForeachFunc func;
1234   const GstTagList *tag_list;
1235   gpointer data;
1236 }
1237 TagForeachData;
1238
1239 static int
1240 structure_foreach_wrapper (GQuark field_id, const GValue * value,
1241     gpointer user_data)
1242 {
1243   TagForeachData *data = (TagForeachData *) user_data;
1244
1245   data->func (data->tag_list, g_quark_to_string (field_id), data->data);
1246   return TRUE;
1247 }
1248
1249 /**
1250  * gst_tag_list_foreach:
1251  * @list: list to iterate over
1252  * @func: (scope call): function to be called for each tag
1253  * @user_data: (closure): user specified data
1254  *
1255  * Calls the given function for each tag inside the tag list. Note that if there
1256  * is no tag, the function won't be called at all.
1257  */
1258 void
1259 gst_tag_list_foreach (const GstTagList * list, GstTagForeachFunc func,
1260     gpointer user_data)
1261 {
1262   TagForeachData data;
1263
1264   g_return_if_fail (GST_IS_TAG_LIST (list));
1265   g_return_if_fail (func != NULL);
1266
1267   data.func = func;
1268   data.tag_list = list;
1269   data.data = user_data;
1270   gst_structure_foreach ((GstStructure *) list, structure_foreach_wrapper,
1271       &data);
1272 }
1273
1274 /**
1275  * gst_tag_list_get_value_index:
1276  * @list: a #GstTagList
1277  * @tag: tag to read out
1278  * @index: number of entry to read out
1279  *
1280  * Gets the value that is at the given index for the given tag in the given
1281  * list.
1282  *
1283  * Returns: (transfer none): The GValue for the specified entry or NULL if the
1284  *          tag wasn't available or the tag doesn't have as many entries
1285  */
1286 const GValue *
1287 gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag,
1288     guint index)
1289 {
1290   const GValue *value;
1291
1292   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
1293   g_return_val_if_fail (tag != NULL, NULL);
1294
1295   value = gst_structure_get_value ((GstStructure *) list, tag);
1296   if (value == NULL)
1297     return NULL;
1298
1299   if (GST_VALUE_HOLDS_LIST (value)) {
1300     if (index >= gst_value_list_get_size (value))
1301       return NULL;
1302     return gst_value_list_get_value (value, index);
1303   } else {
1304     if (index > 0)
1305       return NULL;
1306     return value;
1307   }
1308 }
1309
1310 /**
1311  * gst_tag_list_copy_value:
1312  * @dest: (out caller-allocates): uninitialized #GValue to copy into
1313  * @list: list to get the tag from
1314  * @tag: tag to read out
1315  *
1316  * Copies the contents for the given tag into the value,
1317  * merging multiple values into one if multiple values are associated
1318  * with the tag.
1319  * You must g_value_unset() the value after use.
1320  *
1321  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1322  *          given list.
1323  */
1324 gboolean
1325 gst_tag_list_copy_value (GValue * dest, const GstTagList * list,
1326     const gchar * tag)
1327 {
1328   const GValue *src;
1329
1330   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1331   g_return_val_if_fail (tag != NULL, FALSE);
1332   g_return_val_if_fail (dest != NULL, FALSE);
1333   g_return_val_if_fail (G_VALUE_TYPE (dest) == 0, FALSE);
1334
1335   src = gst_structure_get_value ((GstStructure *) list, tag);
1336   if (!src)
1337     return FALSE;
1338
1339   if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
1340     GstTagInfo *info = gst_tag_lookup (tag);
1341
1342     if (!info)
1343       return FALSE;
1344
1345     /* must be there or lists aren't allowed */
1346     g_assert (info->merge_func);
1347     info->merge_func (dest, src);
1348   } else {
1349     g_value_init (dest, G_VALUE_TYPE (src));
1350     g_value_copy (src, dest);
1351   }
1352   return TRUE;
1353 }
1354
1355 /* FIXME 0.11: this whole merge function business is overdesigned, and the
1356  * _get_foo() API is misleading as well - how many application developers will
1357  * expect gst_tag_list_get_string (list, GST_TAG_ARTIST, &val) might return a
1358  * string with multiple comma-separated artists? _get_foo() should just be
1359  * a convenience wrapper around _get_foo_index (list, tag, 0, &val),
1360  * supplemented by a special _tag_list_get_string_merged() function if needed
1361  * (unless someone can actually think of real use cases where the merge
1362  * function is not 'use first' for non-strings and merge for strings) */
1363
1364 /***** evil macros to get all the gst_tag_list_get_*() functions right *****/
1365
1366 #define TAG_MERGE_FUNCS(name,type,ret)                                  \
1367 gboolean                                                                \
1368 gst_tag_list_get_ ## name (const GstTagList *list, const gchar *tag,    \
1369                            type *value)                                 \
1370 {                                                                       \
1371   GValue v = { 0, };                                                    \
1372                                                                         \
1373   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                 \
1374   g_return_val_if_fail (tag != NULL, FALSE);                            \
1375   g_return_val_if_fail (value != NULL, FALSE);                          \
1376                                                                         \
1377   if (!gst_tag_list_copy_value (&v, list, tag))                         \
1378       return FALSE;                                                     \
1379   *value = COPY_FUNC (g_value_get_ ## name (&v));                       \
1380   g_value_unset (&v);                                                   \
1381   return ret;                                                           \
1382 }                                                                       \
1383                                                                         \
1384 gboolean                                                                \
1385 gst_tag_list_get_ ## name ## _index (const GstTagList *list,            \
1386                                      const gchar *tag,                  \
1387                                      guint index, type *value)          \
1388 {                                                                       \
1389   const GValue *v;                                                      \
1390                                                                         \
1391   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                 \
1392   g_return_val_if_fail (tag != NULL, FALSE);                            \
1393   g_return_val_if_fail (value != NULL, FALSE);                          \
1394                                                                         \
1395   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)    \
1396       return FALSE;                                                     \
1397   *value = COPY_FUNC (g_value_get_ ## name (v));                        \
1398   return ret;                                                           \
1399 }
1400
1401 /* FIXME 0.11: maybe get rid of _get_char*(), _get_uchar*(), _get_long*(),
1402  * _get_ulong*() and _get_pointer*()? - they are not really useful/common
1403  * enough to warrant convenience accessor functions */
1404
1405 #define COPY_FUNC /**/
1406 /**
1407  * gst_tag_list_get_char:
1408  * @list: a #GstTagList to get the tag from
1409  * @tag: tag to read out
1410  * @value: (out): location for the result
1411  *
1412  * Copies the contents for the given tag into the value, merging multiple values
1413  * into one if multiple values are associated with the tag.
1414  *
1415  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1416  *              given list.
1417  */
1418 /**
1419  * gst_tag_list_get_char_index:
1420  * @list: a #GstTagList to get the tag from
1421  * @tag: tag to read out
1422  * @index: number of entry to read out
1423  * @value: (out): location for the result
1424  *
1425  * Gets the value that is at the given index for the given tag in the given
1426  * list.
1427  *
1428  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1429  *              given list.
1430  */
1431 TAG_MERGE_FUNCS (char, gchar, TRUE);
1432 /**
1433  * gst_tag_list_get_uchar:
1434  * @list: a #GstTagList to get the tag from
1435  * @tag: tag to read out
1436  * @value: (out): location for the result
1437  *
1438  * Copies the contents for the given tag into the value, merging multiple values
1439  * into one if multiple values are associated with the tag.
1440  *
1441  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1442  *              given list.
1443  */
1444 /**
1445  * gst_tag_list_get_uchar_index:
1446  * @list: a #GstTagList to get the tag from
1447  * @tag: tag to read out
1448  * @index: number of entry to read out
1449  * @value: (out): location for the result
1450  *
1451  * Gets the value that is at the given index for the given tag in the given
1452  * list.
1453  *
1454  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1455  *              given list.
1456  */
1457 TAG_MERGE_FUNCS (uchar, guchar, TRUE);
1458 /**
1459  * gst_tag_list_get_boolean:
1460  * @list: a #GstTagList to get the tag from
1461  * @tag: tag to read out
1462  * @value: (out): location for the result
1463  *
1464  * Copies the contents for the given tag into the value, merging multiple values
1465  * into one if multiple values are associated with the tag.
1466  *
1467  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1468  *              given list.
1469  */
1470 /**
1471  * gst_tag_list_get_boolean_index:
1472  * @list: a #GstTagList to get the tag from
1473  * @tag: tag to read out
1474  * @index: number of entry to read out
1475  * @value: (out): location for the result
1476  *
1477  * Gets the value that is at the given index for the given tag in the given
1478  * list.
1479  *
1480  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1481  *              given list.
1482  */
1483 TAG_MERGE_FUNCS (boolean, gboolean, TRUE);
1484 /**
1485  * gst_tag_list_get_int:
1486  * @list: a #GstTagList to get the tag from
1487  * @tag: tag to read out
1488  * @value: (out): location for the result
1489  *
1490  * Copies the contents for the given tag into the value, merging multiple values
1491  * into one if multiple values are associated with the tag.
1492  *
1493  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1494  *              given list.
1495  */
1496 /**
1497  * gst_tag_list_get_int_index:
1498  * @list: a #GstTagList to get the tag from
1499  * @tag: tag to read out
1500  * @index: number of entry to read out
1501  * @value: (out): location for the result
1502  *
1503  * Gets the value that is at the given index for the given tag in the given
1504  * list.
1505  *
1506  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1507  *              given list.
1508  */
1509 TAG_MERGE_FUNCS (int, gint, TRUE);
1510 /**
1511  * gst_tag_list_get_uint:
1512  * @list: a #GstTagList to get the tag from
1513  * @tag: tag to read out
1514  * @value: (out): location for the result
1515  *
1516  * Copies the contents for the given tag into the value, merging multiple values
1517  * into one if multiple values are associated with the tag.
1518  *
1519  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1520  *              given list.
1521  */
1522 /**
1523  * gst_tag_list_get_uint_index:
1524  * @list: a #GstTagList to get the tag from
1525  * @tag: tag to read out
1526  * @index: number of entry to read out
1527  * @value: (out): location for the result
1528  *
1529  * Gets the value that is at the given index for the given tag in the given
1530  * list.
1531  *
1532  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1533  *              given list.
1534  */
1535 TAG_MERGE_FUNCS (uint, guint, TRUE);
1536 /**
1537  * gst_tag_list_get_long:
1538  * @list: a #GstTagList to get the tag from
1539  * @tag: tag to read out
1540  * @value: (out): location for the result
1541  *
1542  * Copies the contents for the given tag into the value, merging multiple values
1543  * into one if multiple values are associated with the tag.
1544  *
1545  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1546  *              given list.
1547  */
1548 /**
1549  * gst_tag_list_get_long_index:
1550  * @list: a #GstTagList to get the tag from
1551  * @tag: tag to read out
1552  * @index: number of entry to read out
1553  * @value: (out): location for the result
1554  *
1555  * Gets the value that is at the given index for the given tag in the given
1556  * list.
1557  *
1558  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1559  *              given list.
1560  */
1561 TAG_MERGE_FUNCS (long, glong, TRUE);
1562 /**
1563  * gst_tag_list_get_ulong:
1564  * @list: a #GstTagList to get the tag from
1565  * @tag: tag to read out
1566  * @value: (out): location for the result
1567  *
1568  * Copies the contents for the given tag into the value, merging multiple values
1569  * into one if multiple values are associated with the tag.
1570  *
1571  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1572  *              given list.
1573  */
1574 /**
1575  * gst_tag_list_get_ulong_index:
1576  * @list: a #GstTagList to get the tag from
1577  * @tag: tag to read out
1578  * @index: number of entry to read out
1579  * @value: (out): location for the result
1580  *
1581  * Gets the value that is at the given index for the given tag in the given
1582  * list.
1583  *
1584  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1585  *              given list.
1586  */
1587 TAG_MERGE_FUNCS (ulong, gulong, TRUE);
1588 /**
1589  * gst_tag_list_get_int64:
1590  * @list: a #GstTagList to get the tag from
1591  * @tag: tag to read out
1592  * @value: (out): location for the result
1593  *
1594  * Copies the contents for the given tag into the value, merging multiple values
1595  * into one if multiple values are associated with the tag.
1596  *
1597  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1598  *              given list.
1599  */
1600 /**
1601  * gst_tag_list_get_int64_index:
1602  * @list: a #GstTagList to get the tag from
1603  * @tag: tag to read out
1604  * @index: number of entry to read out
1605  * @value: (out): location for the result
1606  *
1607  * Gets the value that is at the given index for the given tag in the given
1608  * list.
1609  *
1610  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1611  *              given list.
1612  */
1613 TAG_MERGE_FUNCS (int64, gint64, TRUE);
1614 /**
1615  * gst_tag_list_get_uint64:
1616  * @list: a #GstTagList to get the tag from
1617  * @tag: tag to read out
1618  * @value: (out): location for the result
1619  *
1620  * Copies the contents for the given tag into the value, merging multiple values
1621  * into one if multiple values are associated with the tag.
1622  *
1623  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1624  *              given list.
1625  */
1626 /**
1627  * gst_tag_list_get_uint64_index:
1628  * @list: a #GstTagList to get the tag from
1629  * @tag: tag to read out
1630  * @index: number of entry to read out
1631  * @value: (out): location for the result
1632  *
1633  * Gets the value that is at the given index for the given tag in the given
1634  * list.
1635  *
1636  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1637  *              given list.
1638  */
1639 TAG_MERGE_FUNCS (uint64, guint64, TRUE);
1640 /**
1641  * gst_tag_list_get_float:
1642  * @list: a #GstTagList to get the tag from
1643  * @tag: tag to read out
1644  * @value: (out): location for the result
1645  *
1646  * Copies the contents for the given tag into the value, merging multiple values
1647  * into one if multiple values are associated with the tag.
1648  *
1649  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1650  *              given list.
1651  */
1652 /**
1653  * gst_tag_list_get_float_index:
1654  * @list: a #GstTagList to get the tag from
1655  * @tag: tag to read out
1656  * @index: number of entry to read out
1657  * @value: (out): location for the result
1658  *
1659  * Gets the value that is at the given index for the given tag in the given
1660  * list.
1661  *
1662  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1663  *              given list.
1664  */
1665 TAG_MERGE_FUNCS (float, gfloat, TRUE);
1666 /**
1667  * gst_tag_list_get_double:
1668  * @list: a #GstTagList to get the tag from
1669  * @tag: tag to read out
1670  * @value: (out): location for the result
1671  *
1672  * Copies the contents for the given tag into the value, merging multiple values
1673  * into one if multiple values are associated with the tag.
1674  *
1675  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1676  *              given list.
1677  */
1678 /**
1679  * gst_tag_list_get_double_index:
1680  * @list: a #GstTagList to get the tag from
1681  * @tag: tag to read out
1682  * @index: number of entry to read out
1683  * @value: (out): location for the result
1684  *
1685  * Gets the value that is at the given index for the given tag in the given
1686  * list.
1687  *
1688  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1689  *              given list.
1690  */
1691 TAG_MERGE_FUNCS (double, gdouble, TRUE);
1692 /**
1693  * gst_tag_list_get_pointer:
1694  * @list: a #GstTagList to get the tag from
1695  * @tag: tag to read out
1696  * @value: (out) (transfer none): location for the result
1697  *
1698  * Copies the contents for the given tag into the value, merging multiple values
1699  * into one if multiple values are associated with the tag.
1700  *
1701  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1702  *              given list.
1703  */
1704 /**
1705  * gst_tag_list_get_pointer_index:
1706  * @list: a #GstTagList to get the tag from
1707  * @tag: tag to read out
1708  * @index: number of entry to read out
1709  * @value: (out) (transfer none): location for the result
1710  *
1711  * Gets the value that is at the given index for the given tag in the given
1712  * list.
1713  *
1714  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1715  *              given list.
1716  */
1717 TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL));
1718
1719 static inline gchar *
1720 _gst_strdup0 (const gchar * s)
1721 {
1722   if (s == NULL || *s == '\0')
1723     return NULL;
1724
1725   return g_strdup (s);
1726 }
1727
1728 #undef COPY_FUNC
1729 #define COPY_FUNC _gst_strdup0
1730
1731 /**
1732  * gst_tag_list_get_string:
1733  * @list: a #GstTagList to get the tag from
1734  * @tag: tag to read out
1735  * @value: (out callee-allocates) (transfer full): location for the result
1736  *
1737  * Copies the contents for the given tag into the value, possibly merging
1738  * multiple values into one if multiple values are associated with the tag.
1739  *
1740  * Use gst_tag_list_get_string_index (list, tag, 0, value) if you want
1741  * to retrieve the first string associated with this tag unmodified.
1742  *
1743  * The resulting string in @value will be in UTF-8 encoding and should be
1744  * freed by the caller using g_free when no longer needed. Since 0.10.24 the
1745  * returned string is also guaranteed to be non-NULL and non-empty.
1746  *
1747  * Free-function: g_free
1748  *
1749  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1750  *              given list.
1751  */
1752 /**
1753  * gst_tag_list_get_string_index:
1754  * @list: a #GstTagList to get the tag from
1755  * @tag: tag to read out
1756  * @index: number of entry to read out
1757  * @value: (out callee-allocates) (transfer full): location for the result
1758  *
1759  * Gets the value that is at the given index for the given tag in the given
1760  * list.
1761  *
1762  * The resulting string in @value will be in UTF-8 encoding and should be
1763  * freed by the caller using g_free when no longer needed. Since 0.10.24 the
1764  * returned string is also guaranteed to be non-NULL and non-empty.
1765  *
1766  * Free-function: g_free
1767  *
1768  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1769  *              given list.
1770  */
1771 TAG_MERGE_FUNCS (string, gchar *, (*value != NULL));
1772
1773 /*
1774  *FIXME 0.11: Instead of _peek (non-copy) and _get (copy), we could have
1775  *            _get (non-copy) and _dup (copy) for strings, seems more
1776  *            widely used
1777  */
1778 /**
1779  * gst_tag_list_peek_string_index:
1780  * @list: a #GstTagList to get the tag from
1781  * @tag: tag to read out
1782  * @index: number of entry to read out
1783  * @value: (out) (transfer none): location for the result
1784  *
1785  * Peeks at the value that is at the given index for the given tag in the given
1786  * list.
1787  *
1788  * The resulting string in @value will be in UTF-8 encoding and doesn't need
1789  * to be freed by the caller. The returned string is also guaranteed to
1790  * be non-NULL and non-empty.
1791  *
1792  * Returns: TRUE, if a value was set, FALSE if the tag didn't exist in the
1793  *              given list.
1794  */
1795 gboolean
1796 gst_tag_list_peek_string_index (const GstTagList * list,
1797     const gchar * tag, guint index, const gchar ** 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 = g_value_get_string (v);
1808   return *value != NULL && **value != '\0';
1809 }
1810
1811 /**
1812  * gst_tag_list_get_date:
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 GDate pointer
1816  *     variable to store the result into
1817  *
1818  * Copies the first date for the given tag in the taglist into the variable
1819  * pointed to by @value. Free the date with g_date_free() when it is no longer
1820  * needed.
1821  *
1822  * Free-function: g_date_free
1823  *
1824  * Returns: TRUE, if a date was copied, FALSE if the tag didn't exist in the
1825  *              given list or if it was #NULL.
1826  */
1827 gboolean
1828 gst_tag_list_get_date (const GstTagList * list, const gchar * tag,
1829     GDate ** value)
1830 {
1831   GValue v = { 0, };
1832
1833   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1834   g_return_val_if_fail (tag != NULL, FALSE);
1835   g_return_val_if_fail (value != NULL, FALSE);
1836
1837   if (!gst_tag_list_copy_value (&v, list, tag))
1838     return FALSE;
1839   *value = (GDate *) g_value_dup_boxed (&v);
1840   g_value_unset (&v);
1841   return (*value != NULL);
1842 }
1843
1844 /**
1845  * gst_tag_list_get_date_index:
1846  * @list: a #GstTagList to get the tag from
1847  * @tag: tag to read out
1848  * @index: number of entry to read out
1849  * @value: (out callee-allocates) (transfer full): location for the result
1850  *
1851  * Gets the date that is at the given index for the given tag in the given
1852  * list and copies it into the variable pointed to by @value. Free the date
1853  * with g_date_free() when it is no longer needed.
1854  *
1855  * Free-function: g_date_free
1856  *
1857  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1858  *              given list or if it was #NULL.
1859  */
1860 gboolean
1861 gst_tag_list_get_date_index (const GstTagList * list,
1862     const gchar * tag, guint index, GDate ** value)
1863 {
1864   const GValue *v;
1865
1866   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1867   g_return_val_if_fail (tag != NULL, FALSE);
1868   g_return_val_if_fail (value != NULL, FALSE);
1869
1870   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1871     return FALSE;
1872   *value = (GDate *) g_value_dup_boxed (v);
1873   return (*value != NULL);
1874 }
1875
1876 /**
1877  * gst_tag_list_get_date_time:
1878  * @list: a #GstTagList to get the tag from
1879  * @tag: tag to read out
1880  * @value: (out callee-allocates) (transfer full): address of a #GstDateTime
1881  *     pointer variable to store the result into
1882  *
1883  * Copies the first datetime for the given tag in the taglist into the variable
1884  * pointed to by @value. Unref the date with gst_date_time_unref() when
1885  * it is no longer needed.
1886  *
1887  * Free-function: gst_date_time_unref
1888  *
1889  * Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in
1890  *              thegiven list or if it was #NULL.
1891  *
1892  * Since: 0.10.31
1893  */
1894 gboolean
1895 gst_tag_list_get_date_time (const GstTagList * list, const gchar * tag,
1896     GstDateTime ** value)
1897 {
1898   GValue v = { 0, };
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 (!gst_tag_list_copy_value (&v, list, tag))
1905     return FALSE;
1906
1907   g_return_val_if_fail (GST_VALUE_HOLDS_DATE_TIME (&v), FALSE);
1908
1909   *value = (GstDateTime *) g_value_dup_boxed (&v);
1910   g_value_unset (&v);
1911   return (*value != NULL);
1912 }
1913
1914 /**
1915  * gst_tag_list_get_date_time_index:
1916  * @list: a #GstTagList to get the tag from
1917  * @tag: tag to read out
1918  * @index: number of entry to read out
1919  * @value: (out callee-allocates) (transfer full): location for the result
1920  *
1921  * Gets the datetime that is at the given index for the given tag in the given
1922  * list and copies it into the variable pointed to by @value. Unref the datetime
1923  * with gst_date_time_unref() when it is no longer needed.
1924  *
1925  * Free-function: gst_date_time_unref
1926  *
1927  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
1928  *              given list or if it was #NULL.
1929  *
1930  * Since: 0.10.31
1931  */
1932 gboolean
1933 gst_tag_list_get_date_time_index (const GstTagList * list,
1934     const gchar * tag, guint index, GstDateTime ** value)
1935 {
1936   const GValue *v;
1937
1938   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1939   g_return_val_if_fail (tag != NULL, FALSE);
1940   g_return_val_if_fail (value != NULL, FALSE);
1941
1942   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
1943     return FALSE;
1944   *value = (GstDateTime *) g_value_dup_boxed (v);
1945   return (*value != NULL);
1946 }
1947
1948 /**
1949  * gst_tag_list_get_buffer:
1950  * @list: a #GstTagList to get the tag from
1951  * @tag: tag to read out
1952  * @value: (out callee-allocates) (transfer full): address of a GstBuffer
1953  *     pointer variable to store the result into
1954  *
1955  * Copies the first buffer for the given tag in the taglist into the variable
1956  * pointed to by @value. Free the buffer with gst_buffer_unref() when it is
1957  * no longer needed.
1958  *
1959  * Free-function: gst_buffer_unref
1960  *
1961  * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
1962  *              given list or if it was #NULL.
1963  *
1964  * Since: 0.10.23
1965  */
1966 gboolean
1967 gst_tag_list_get_buffer (const GstTagList * list, const gchar * tag,
1968     GstBuffer ** value)
1969 {
1970   GValue v = { 0, };
1971
1972   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
1973   g_return_val_if_fail (tag != NULL, FALSE);
1974   g_return_val_if_fail (value != NULL, FALSE);
1975
1976   if (!gst_tag_list_copy_value (&v, list, tag))
1977     return FALSE;
1978   *value = g_value_dup_boxed (&v);
1979   g_value_unset (&v);
1980   return (*value != NULL);
1981 }
1982
1983 /**
1984  * gst_tag_list_get_buffer_index:
1985  * @list: a #GstTagList to get the tag from
1986  * @tag: tag to read out
1987  * @index: number of entry to read out
1988  * @value: (out callee-allocates) (transfer full): address of a GstBuffer
1989  *     pointer variable to store the result into
1990  *
1991  * Gets the buffer that is at the given index for the given tag in the given
1992  * list and copies it into the variable pointed to by @value. Free the buffer
1993  * with gst_buffer_unref() when it is no longer needed.
1994  *
1995  * Free-function: gst_buffer_unref
1996  *
1997  * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
1998  *              given list or if it was #NULL.
1999  *
2000  * Since: 0.10.23
2001  */
2002 gboolean
2003 gst_tag_list_get_buffer_index (const GstTagList * list,
2004     const gchar * tag, guint index, GstBuffer ** value)
2005 {
2006   const GValue *v;
2007
2008   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
2009   g_return_val_if_fail (tag != NULL, FALSE);
2010   g_return_val_if_fail (value != NULL, FALSE);
2011
2012   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
2013     return FALSE;
2014   *value = g_value_dup_boxed (v);
2015   return (*value != NULL);
2016 }