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