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