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