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