gst/gsttag.c

   1 /* GStreamer
   2  * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
   3  *
   4  * gsttag.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 #ifdef HAVE_CONFIG_H
  23 #  include "config.h"
  24 #endif
  25
  26 #include "gst_private.h"
  27 #include "gst-i18n-lib.h"
  28 #include "gsttag.h"
  29 #include "gstinfo.h"
  30 #include "gstvalue.h"
  31
  32 #include <gobject/gvaluecollector.h>
  33 #include <string.h>
  34
  35 #define GST_TAG_IS_VALID(tag)           (gst_tag_get_info (tag) != NULL)
  36
  37 typedef struct
  38 {
  39   GType type;                   /* type the data is in */
  40
  41   gchar *nick;                  /* translated name */
  42   gchar *blurb;                 /* translated description of type */
  43
  44   GstTagMergeFunc merge_func;   /* functions to merge the values */
  45   GstTagFlag flag;              /* type of tag */
  46 }
  47 GstTagInfo;
  48
  49 #define TAGLIST "taglist"
  50 static GQuark gst_tag_list_quark;
  51 static GMutex *__tag_mutex;
  52 static GHashTable *__tags;
  53
  54 #define TAG_LOCK g_mutex_lock (__tag_mutex)
  55 #define TAG_UNLOCK g_mutex_unlock (__tag_mutex)
  56
  57 GType
  58 gst_tag_list_get_type (void)
  59 {
  60   static GType _gst_tag_list_type;
  61
  62   if (_gst_tag_list_type == 0) {
  63     _gst_tag_list_type = g_boxed_type_register_static ("GstTagList",
  64         (GBoxedCopyFunc) gst_tag_list_copy, (GBoxedFreeFunc) gst_tag_list_free);
  65
  66 #if 0
  67     g_value_register_transform_func (_gst_tag_list_type, G_TYPE_STRING,
  68         _gst_structure_transform_to_string);
  69 #endif
  70   }
  71
  72   return _gst_tag_list_type;
  73 }
  74
  75 void
  76 _gst_tag_initialize (void)
  77 {
  78   gst_tag_list_quark = g_quark_from_static_string (TAGLIST);
  79   __tag_mutex = g_mutex_new ();
  80   __tags = g_hash_table_new (g_direct_hash, g_direct_equal);
  81   gst_tag_register (GST_TAG_TITLE, GST_TAG_FLAG_META,
  82       G_TYPE_STRING,
  83       _("title"), _("commonly used title"), gst_tag_merge_strings_with_comma);
  84   gst_tag_register (GST_TAG_ARTIST, GST_TAG_FLAG_META,
  85       G_TYPE_STRING,
  86       _("artist"),
  87       _("person(s) responsible for the recording"),
  88       gst_tag_merge_strings_with_comma);
  89   gst_tag_register (GST_TAG_ALBUM, GST_TAG_FLAG_META,
  90       G_TYPE_STRING,
  91       _("album"),
  92       _("album containing this data"), gst_tag_merge_strings_with_comma);
  93   gst_tag_register (GST_TAG_DATE, GST_TAG_FLAG_META, G_TYPE_UINT,       /* FIXME: own data type for dates? */
  94       _("date"),
  95       _("date the data was created (in Julian calendar days)"), NULL);
  96   gst_tag_register (GST_TAG_GENRE, GST_TAG_FLAG_META,
  97       G_TYPE_STRING,
  98       _("genre"),
  99       _("genre this data belongs to"), gst_tag_merge_strings_with_comma);
 100   gst_tag_register (GST_TAG_COMMENT, GST_TAG_FLAG_META,
 101       G_TYPE_STRING,
 102       _("comment"),
 103       _("free text commenting the data"), gst_tag_merge_strings_with_comma);
 104   gst_tag_register (GST_TAG_TRACK_NUMBER, GST_TAG_FLAG_META,
 105       G_TYPE_UINT,
 106       _("track number"),
 107       _("track number inside a collection"), gst_tag_merge_use_first);
 108   gst_tag_register (GST_TAG_TRACK_COUNT, GST_TAG_FLAG_META,
 109       G_TYPE_UINT,
 110       _("track count"),
 111       _("count of tracks inside collection this track belongs to"),
 112       gst_tag_merge_use_first);
 113   gst_tag_register (GST_TAG_ALBUM_VOLUME_NUMBER, GST_TAG_FLAG_META,
 114       G_TYPE_UINT,
 115       _("disc number"),
 116       _("disc number inside a collection"), gst_tag_merge_use_first);
 117   gst_tag_register (GST_TAG_ALBUM_VOLUME_COUNT, GST_TAG_FLAG_META,
 118       G_TYPE_UINT,
 119       _("disc count"),
 120       _("count of discs inside collection this disc belongs to"),
 121       gst_tag_merge_use_first);
 122   gst_tag_register (GST_TAG_LOCATION, GST_TAG_FLAG_META,
 123       G_TYPE_STRING,
 124       _("location"),
 125       _("original location of file as a URI"),
 126       gst_tag_merge_strings_with_comma);
 127   gst_tag_register (GST_TAG_DESCRIPTION, GST_TAG_FLAG_META,
 128       G_TYPE_STRING,
 129       _("description"),
 130       _("short text describing the content of the data"),
 131       gst_tag_merge_strings_with_comma);
 132   gst_tag_register (GST_TAG_VERSION, GST_TAG_FLAG_META,
 133       G_TYPE_STRING, _("version"), _("version of this data"), NULL);
 134   gst_tag_register (GST_TAG_ISRC, GST_TAG_FLAG_META,
 135       G_TYPE_STRING,
 136       _("ISRC"),
 137       _
 138       ("International Standard Recording Code - see http://www.ifpi.org/isrc/"),
 139       NULL);
 140   gst_tag_register (GST_TAG_ORGANIZATION, GST_TAG_FLAG_META, G_TYPE_STRING, _("organization"), _("organization"),       /* FIXME */
 141       gst_tag_merge_strings_with_comma);
 142   gst_tag_register (GST_TAG_COPYRIGHT, GST_TAG_FLAG_META,
 143       G_TYPE_STRING, _("copyright"), _("copyright notice of the data"), NULL);
 144   gst_tag_register (GST_TAG_CONTACT, GST_TAG_FLAG_META,
 145       G_TYPE_STRING,
 146       _("contact"), _("contact information"), gst_tag_merge_strings_with_comma);
 147   gst_tag_register (GST_TAG_LICENSE, GST_TAG_FLAG_META,
 148       G_TYPE_STRING, _("license"), _("license of data"), NULL);
 149   gst_tag_register (GST_TAG_PERFORMER, GST_TAG_FLAG_META,
 150       G_TYPE_STRING,
 151       _("performer"),
 152       _("person(s) performing"), gst_tag_merge_strings_with_comma);
 153   gst_tag_register (GST_TAG_DURATION, GST_TAG_FLAG_DECODED,
 154       G_TYPE_UINT64,
 155       _("duration"), _("length in GStreamer time units (nanoseconds)"), NULL);
 156   gst_tag_register (GST_TAG_CODEC, GST_TAG_FLAG_ENCODED,
 157       G_TYPE_STRING,
 158       _("codec"),
 159       _("codec the data is stored in"), gst_tag_merge_strings_with_comma);
 160   gst_tag_register (GST_TAG_VIDEO_CODEC, GST_TAG_FLAG_ENCODED,
 161       G_TYPE_STRING,
 162       _("video codec"), _("codec the video data is stored in"), NULL);
 163   gst_tag_register (GST_TAG_AUDIO_CODEC, GST_TAG_FLAG_ENCODED,
 164       G_TYPE_STRING,
 165       _("audio codec"), _("codec the audio data is stored in"), NULL);
 166   gst_tag_register (GST_TAG_BITRATE, GST_TAG_FLAG_ENCODED,
 167       G_TYPE_UINT, _("bitrate"), _("exact or average bitrate in bits/s"), NULL);
 168   gst_tag_register (GST_TAG_NOMINAL_BITRATE, GST_TAG_FLAG_ENCODED,
 169       G_TYPE_UINT, _("nominal bitrate"), _("nominal bitrate in bits/s"), NULL);
 170   gst_tag_register (GST_TAG_MINIMUM_BITRATE, GST_TAG_FLAG_ENCODED,
 171       G_TYPE_UINT, _("minimum bitrate"), _("minimum bitrate in bits/s"), NULL);
 172   gst_tag_register (GST_TAG_MAXIMUM_BITRATE, GST_TAG_FLAG_ENCODED,
 173       G_TYPE_UINT, _("maximum bitrate"), _("maximum bitrate in bits/s"), NULL);
 174   gst_tag_register (GST_TAG_ENCODER, GST_TAG_FLAG_ENCODED,
 175       G_TYPE_STRING,
 176       _("encoder"), _("encoder used to encode this stream"), NULL);
 177   gst_tag_register (GST_TAG_ENCODER_VERSION, GST_TAG_FLAG_ENCODED,
 178       G_TYPE_UINT,
 179       _("encoder version"),
 180       _("version of the encoder used to encode this stream"), NULL);
 181   gst_tag_register (GST_TAG_SERIAL, GST_TAG_FLAG_ENCODED,
 182       G_TYPE_UINT, _("serial"), _("serial number of track"), NULL);
 183   gst_tag_register (GST_TAG_TRACK_GAIN, GST_TAG_FLAG_META,
 184       G_TYPE_DOUBLE, _("replaygain track gain"), _("track gain in db"), NULL);
 185   gst_tag_register (GST_TAG_TRACK_PEAK, GST_TAG_FLAG_META,
 186       G_TYPE_DOUBLE, _("replaygain track peak"), _("peak of the track"), NULL);
 187   gst_tag_register (GST_TAG_ALBUM_GAIN, GST_TAG_FLAG_META,
 188       G_TYPE_DOUBLE, _("replaygain album gain"), _("album gain in db"), NULL);
 189   gst_tag_register (GST_TAG_ALBUM_PEAK, GST_TAG_FLAG_META,
 190       G_TYPE_DOUBLE, _("replaygain album peak"), _("peak of the album"), NULL);
 191 }
 192
 193 /**
 194  * gst_tag_merge_use_first:
 195  * @dest: uninitialized GValue to store result in
 196  * @src: GValue to copy from
 197  *
 198  * This is a convenience function for the func argument of gst_tag_register().
 199  * It creates a copy of the first value from the list.
 200  */
 201 void
 202 gst_tag_merge_use_first (GValue * dest, const GValue * src)
 203 {
 204   const GValue *ret = gst_value_list_get_value (src, 0);
 205
 206   g_value_init (dest, G_VALUE_TYPE (ret));
 207   g_value_copy (ret, dest);
 208 }
 209
 210 /**
 211  * gst_tag_merge_strings_with_comma:
 212  * @dest: uninitialized GValue to store result in
 213  * @src: GValue to copy from
 214  *
 215  * This is a convenience function for the func argument of gst_tag_register().
 216  * It concatenates all given strings using a comma. The tag must be registered
 217  * as a G_TYPE_STRING or this function will fail.
 218  */
 219 void
 220 gst_tag_merge_strings_with_comma (GValue * dest, const GValue * src)
 221 {
 222   GString *str;
 223   gint i, count;
 224
 225   count = gst_value_list_get_size (src);
 226   str = g_string_new (g_value_get_string (gst_value_list_get_value (src, 0)));
 227   for (i = 1; i < count; i++) {
 228     /* seperator between two string */
 229     str = g_string_append (str, _(", "));
 230     str =
 231         g_string_append (str, g_value_get_string (gst_value_list_get_value (src,
 232                 1)));
 233   }
 234
 235   g_value_init (dest, G_TYPE_STRING);
 236   g_value_set_string_take_ownership (dest, str->str);
 237   g_string_free (str, FALSE);
 238 }
 239 static GstTagInfo *
 240 gst_tag_lookup (GQuark entry)
 241 {
 242   GstTagInfo *ret;
 243
 244   TAG_LOCK;
 245   ret = g_hash_table_lookup (__tags, GUINT_TO_POINTER (entry));
 246   TAG_UNLOCK;
 247
 248   return ret;
 249 }
 250
 251 /**
 252  * gst_tag_register:
 253  * @name: the name or identifier string
 254  * @flag: a flag describing the type of tag info
 255  * @type: the type this data is in
 256  * @nick: human-readable name
 257  * @blurb: a human-readable description about this tag
 258  * @func: function for merging multiple values of this tag
 259  *
 260  * Registers a new tag type for the use with GStreamer's type system. If a type
 261  * with that name is already registered, that one is used.
 262  * The old registration may have used a different type however. So don't rely
 263  * on your supplied values.
 264  * This function takes ownership of all supplied variables.
 265  */
 266 void
 267 gst_tag_register (gchar * name, GstTagFlag flag, GType type,
 268     gchar * nick, gchar * blurb, GstTagMergeFunc func)
 269 {
 270   GQuark key;
 271   GstTagInfo *info;
 272
 273   g_return_if_fail (name != NULL);
 274   g_return_if_fail (nick != NULL);
 275   g_return_if_fail (blurb != NULL);
 276   g_return_if_fail (type != 0 && type != GST_TYPE_LIST);
 277
 278   key = g_quark_from_string (name);
 279   info = gst_tag_lookup (key);
 280   g_return_if_fail (info == NULL);
 281
 282   info = g_new (GstTagInfo, 1);
 283   info->flag = flag;
 284   info->type = type;
 285   info->nick = nick;
 286   info->blurb = blurb;
 287   info->merge_func = func;
 288
 289   TAG_LOCK;
 290   g_hash_table_insert (__tags, GUINT_TO_POINTER (key), info);
 291   TAG_UNLOCK;
 292 }
 293
 294 /**
 295  * gst_tag_exists:
 296  * @tag: name of the tag
 297  *
 298  * Checks if the given type is already registered.
 299  *
 300  * Returns: TRUE if the type is already registered
 301  */
 302 gboolean
 303 gst_tag_exists (const gchar * tag)
 304 {
 305   g_return_val_if_fail (tag != NULL, FALSE);
 306
 307   return gst_tag_lookup (g_quark_from_string (tag)) != NULL;
 308 }
 309
 310 /**
 311  * gst_tag_get_type:
 312  * @tag: the tag
 313  *
 314  * Gets the #GType used for this tag.
 315  *
 316  * Returns: the #GType of this tag
 317  */
 318 GType
 319 gst_tag_get_type (const gchar * tag)
 320 {
 321   GstTagInfo *info;
 322
 323   g_return_val_if_fail (tag != NULL, 0);
 324   info = gst_tag_lookup (g_quark_from_string (tag));
 325   g_return_val_if_fail (info != NULL, 0);
 326
 327   return info->type;
 328 }
 329
 330 /**
 331  * gst_tag_get_nick
 332  * @tag: the tag
 333  *
 334  * Returns the human-readable name of this tag, You must not change or free
 335  * this string.
 336  *
 337  * Returns: the human-readable name of this tag
 338  */
 339 const gchar *
 340 gst_tag_get_nick (const gchar * tag)
 341 {
 342   GstTagInfo *info;
 343
 344   g_return_val_if_fail (tag != NULL, NULL);
 345   info = gst_tag_lookup (g_quark_from_string (tag));
 346   g_return_val_if_fail (info != NULL, NULL);
 347
 348   return info->nick;
 349 }
 350
 351 /**
 352  * gst_tag_get_description:
 353  * @tag: the tag
 354  *
 355  * Returns the human-readable description of this tag, You must not change or
 356  * free this string.
 357  *
 358  * Return the human-readable description of this tag
 359  */
 360 const gchar *
 361 gst_tag_get_description (const gchar * tag)
 362 {
 363   GstTagInfo *info;
 364
 365   g_return_val_if_fail (tag != NULL, NULL);
 366   info = gst_tag_lookup (g_quark_from_string (tag));
 367   g_return_val_if_fail (info != NULL, NULL);
 368
 369   return info->blurb;
 370 }
 371
 372 /**
 373  * gst_tag_get_flag:
 374  * @tag: the tag
 375  *
 376  * Returns the flag of this tag.
 377  */
 378 GstTagFlag
 379 gst_tag_get_flag (const gchar * tag)
 380 {
 381   GstTagInfo *info;
 382
 383   g_return_val_if_fail (tag != NULL, GST_TAG_FLAG_UNDEFINED);
 384   info = gst_tag_lookup (g_quark_from_string (tag));
 385   g_return_val_if_fail (info != NULL, GST_TAG_FLAG_UNDEFINED);
 386
 387   return info->flag;
 388 }
 389
 390 /**
 391  * gst_tag_list_is_fixed:
 392  * @tag: tag to check
 393  *
 394  * Checks if the given tag is fixed. A fixed tag can only contain one value.
 395  * Unfixed tags can contain lists of values.
 396  *
 397  * Returns: TRUE, if the given tag is fixed.
 398  */
 399 gboolean
 400 gst_tag_is_fixed (const gchar * tag)
 401 {
 402   GstTagInfo *info;
 403
 404   g_return_val_if_fail (tag != NULL, FALSE);
 405   info = gst_tag_lookup (g_quark_from_string (tag));
 406   g_return_val_if_fail (info != NULL, FALSE);
 407
 408   return info->merge_func == NULL;
 409 }
 410
 411 /**
 412  * gst_tag_list_new:
 413  *
 414  * Creates a new empty GstTagList.
 415  *
 416  * Returns: An empty tag list
 417  */
 418 GstTagList *
 419 gst_tag_list_new (void)
 420 {
 421   return GST_TAG_LIST (gst_structure_new (TAGLIST, NULL));
 422 }
 423
 424 /**
 425  * gst_is_tag_list:
 426  * @p: Object that might be a taglist
 427  *
 428  * Checks if the given pointer is a taglist.
 429  *
 430  * Returns: TRUE, if the given pointer is a taglist
 431  */
 432 gboolean
 433 gst_is_tag_list (gconstpointer p)
 434 {
 435   g_return_val_if_fail (p != NULL, FALSE);
 436
 437   return ((GstStructure *) p)->name == gst_tag_list_quark;
 438 }
 439 typedef struct
 440 {
 441   GstStructure *list;
 442   GstTagMergeMode mode;
 443 }
 444 GstTagCopyData;
 445 static void
 446 gst_tag_list_add_value_internal (GstStructure * list, GstTagMergeMode mode,
 447     GQuark tag, GValue * value)
 448 {
 449   GstTagInfo *info = gst_tag_lookup (tag);
 450   const GValue *value2;
 451
 452   g_assert (info != NULL);
 453
 454   if (info->merge_func
 455       && (value2 = gst_structure_id_get_value (list, tag)) != NULL) {
 456     GValue dest = { 0, };
 457
 458     switch (mode) {
 459       case GST_TAG_MERGE_REPLACE_ALL:
 460       case GST_TAG_MERGE_REPLACE:
 461         gst_structure_id_set_value (list, tag, value);
 462         break;
 463       case GST_TAG_MERGE_PREPEND:
 464         gst_value_list_concat (&dest, value, value2);
 465         gst_structure_id_set_value (list, tag, &dest);
 466         g_value_unset (&dest);
 467         break;
 468       case GST_TAG_MERGE_APPEND:
 469         gst_value_list_concat (&dest, value2, value);
 470         gst_structure_id_set_value (list, tag, &dest);
 471         g_value_unset (&dest);
 472         break;
 473       case GST_TAG_MERGE_KEEP:
 474       case GST_TAG_MERGE_KEEP_ALL:
 475         break;
 476       default:
 477         g_assert_not_reached ();
 478         break;
 479     }
 480   } else {
 481     switch (mode) {
 482       case GST_TAG_MERGE_APPEND:
 483       case GST_TAG_MERGE_KEEP:
 484         if (gst_structure_id_get_value (list, tag) != NULL)
 485           break;
 486         /* fall through */
 487       case GST_TAG_MERGE_REPLACE_ALL:
 488       case GST_TAG_MERGE_REPLACE:
 489       case GST_TAG_MERGE_PREPEND:
 490         gst_structure_id_set_value (list, tag, value);
 491         break;
 492       case GST_TAG_MERGE_KEEP_ALL:
 493         break;
 494       default:
 495         g_assert_not_reached ();
 496         break;
 497     }
 498   }
 499 }
 500 static gboolean
 501 gst_tag_list_copy_foreach (GQuark tag, GValue * value, gpointer user_data)
 502 {
 503   GstTagCopyData *copy = (GstTagCopyData *) user_data;
 504
 505   gst_tag_list_add_value_internal (copy->list, copy->mode, tag, value);
 506
 507   return TRUE;
 508 }
 509
 510 /**
 511  * gst_tag_list_insert:
 512  * @into: list to merge into
 513  * @from: list to merge from
 514  * @mode: the mode to use
 515  *
 516  * Inserts the tags of the second list into the first list using the given mode.
 517  */
 518 void
 519 gst_tag_list_insert (GstTagList * into, const GstTagList * from,
 520     GstTagMergeMode mode)
 521 {
 522   GstTagCopyData data;
 523
 524   g_return_if_fail (GST_IS_TAG_LIST (into));
 525   g_return_if_fail (GST_IS_TAG_LIST (from));
 526   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
 527
 528   data.list = (GstStructure *) into;
 529   data.mode = mode;
 530   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
 531     gst_structure_remove_all_fields (data.list);
 532   }
 533   gst_structure_foreach ((GstStructure *) from, gst_tag_list_copy_foreach,
 534       &data);
 535 }
 536
 537 /**
 538  * gst_tag_list_copy:
 539  * @list: list to copy
 540  *
 541  * Copies a given #GstTagList.
 542  *
 543  * Returns: copy of the given list
 544  */
 545 GstTagList *
 546 gst_tag_list_copy (const GstTagList * list)
 547 {
 548   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
 549
 550   return GST_TAG_LIST (gst_structure_copy ((GstStructure *) list));
 551 }
 552
 553 /**
 554  * gst_tag_list_merge:
 555  * @list1: first list to merge
 556  * @list2: second list to merge
 557  * @mode: the mode to use
 558  *
 559  * Merges the two given lists into a new list. If one of the lists is NULL, a
 560  * copy of the other is returned. If both lists are NULL, NULL is returned.
 561  *
 562  * Returns: the new list
 563  */
 564 GstTagList *
 565 gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2,
 566     GstTagMergeMode mode)
 567 {
 568   g_return_val_if_fail (list1 == NULL || GST_IS_TAG_LIST (list1), NULL);
 569   g_return_val_if_fail (list2 == NULL || GST_IS_TAG_LIST (list2), NULL);
 570   g_return_val_if_fail (GST_TAG_MODE_IS_VALID (mode), NULL);
 571
 572   if (!list1 && !list2) {
 573     return NULL;
 574   } else if (!list1) {
 575     return gst_tag_list_copy (list2);
 576   } else if (!list2) {
 577     return gst_tag_list_copy (list1);
 578   } else {
 579     GstTagList *ret;
 580
 581     ret = gst_tag_list_copy (list1);
 582     gst_tag_list_insert (ret, list2, mode);
 583     return ret;
 584   }
 585 }
 586
 587 /**
 588  * gst_tag_list_free:
 589  * @list: the list to free
 590  *
 591  * Frees the given list and all associated values.
 592  */
 593 void
 594 gst_tag_list_free (GstTagList * list)
 595 {
 596   g_return_if_fail (GST_IS_TAG_LIST (list));
 597   gst_structure_free ((GstStructure *) list);
 598 }
 599
 600 /**
 601  * gst_tag_list_get_tag_size:
 602  * @list: a taglist
 603  * @tag: the tag to query
 604  *
 605  * Checks how many value are stored in this tag list for the given tag.
 606  *
 607  * Returns: The number of tags stored
 608  */
 609 guint
 610 gst_tag_list_get_tag_size (const GstTagList * list, const gchar * tag)
 611 {
 612   const GValue *value;
 613
 614   g_return_val_if_fail (GST_IS_TAG_LIST (list), 0);
 615
 616   value = gst_structure_get_value ((GstStructure *) list, tag);
 617   if (value == NULL)
 618     return 0;
 619   if (G_VALUE_TYPE (value) != GST_TYPE_LIST)
 620     return 1;
 621
 622   return gst_value_list_get_size (value);
 623 }
 624
 625 /**
 626  * gst_tag_list_add:
 627  * @list: list to set tags in
 628  * @mode: the mode to use
 629  * @tag: tag
 630  * @...: NULL-terminated list of values to set
 631  *
 632  * Sets the values for the given tags using the specified mode.
 633  */
 634 void
 635 gst_tag_list_add (GstTagList * list, GstTagMergeMode mode, const gchar * tag,
 636     ...)
 637 {
 638   va_list args;
 639
 640   g_return_if_fail (GST_IS_TAG_LIST (list));
 641   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
 642   g_return_if_fail (tag != NULL);
 643
 644   va_start (args, tag);
 645   gst_tag_list_add_valist (list, mode, tag, args);
 646   va_end (args);
 647 }
 648
 649 /**
 650  * gst_tag_list_add_values:
 651  * @list: list to set tags in
 652  * @mode: the mode to use
 653  * @tag: tag
 654  * @...: GValues to set
 655  *
 656  * Sets the GValues for the given tags using the specified mode.
 657  */
 658 void
 659 gst_tag_list_add_values (GstTagList * list, GstTagMergeMode mode,
 660     const gchar * tag, ...)
 661 {
 662   va_list args;
 663
 664   g_return_if_fail (GST_IS_TAG_LIST (list));
 665   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
 666   g_return_if_fail (tag != NULL);
 667
 668   va_start (args, tag);
 669   gst_tag_list_add_valist_values (list, mode, tag, args);
 670   va_end (args);
 671 }
 672
 673 /**
 674  * gst_tag_list_add_valist:
 675  * @list: list to set tags in
 676  * @mode: the mode to use
 677  * @tag: tag
 678  * @var_args: tag / value pairs to set
 679  *
 680  * Sets the values for the given tags using the specified mode.
 681  */
 682 void
 683 gst_tag_list_add_valist (GstTagList * list, GstTagMergeMode mode,
 684     const gchar * tag, va_list var_args)
 685 {
 686   GstTagInfo *info;
 687   GQuark quark;
 688   gchar *error = NULL;
 689
 690   g_return_if_fail (GST_IS_TAG_LIST (list));
 691   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
 692   g_return_if_fail (tag != NULL);
 693
 694   while (tag != NULL) {
 695     GValue value = { 0, };
 696
 697     quark = g_quark_from_string (tag);
 698     info = gst_tag_lookup (quark);
 699     if (info == NULL)
 700       g_warning ("no GstTag for %s", tag);
 701     g_return_if_fail (info != NULL);
 702     g_value_init (&value, info->type);
 703     G_VALUE_COLLECT (&value, var_args, 0, &error);
 704     if (error) {
 705       g_warning ("%s: %s", G_STRLOC, error);
 706       g_free (error);
 707       /* we purposely leak the value here, it might not be
 708        * in a sane state if an error condition occoured
 709        */
 710       return;
 711     }
 712     gst_tag_list_add_value_internal (list, mode, quark, &value);
 713     g_value_unset (&value);
 714     tag = va_arg (var_args, gchar *);
 715   }
 716 }
 717
 718 /**
 719  * gst_tag_list_add_valist_values:
 720  * @list: list to set tags in
 721  * @mode: the mode to use
 722  * @tag: tag
 723  * @var_args: tag / GValue pairs to set
 724  *
 725  * Sets the GValues for the given tags using the specified mode.
 726  */
 727 void
 728 gst_tag_list_add_valist_values (GstTagList * list, GstTagMergeMode mode,
 729     const gchar * tag, va_list var_args)
 730 {
 731   GstTagInfo *info;
 732   GQuark quark;
 733
 734   g_return_if_fail (GST_IS_TAG_LIST (list));
 735   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
 736   g_return_if_fail (tag != NULL);
 737
 738   while (tag != NULL) {
 739     quark = g_quark_from_string (tag);
 740     info = gst_tag_lookup (quark);
 741     g_return_if_fail (info != NULL);
 742     gst_tag_list_add_value_internal (list, mode, quark, va_arg (var_args,
 743             GValue *));
 744     tag = va_arg (var_args, gchar *);
 745   }
 746 }
 747
 748 /**
 749  * gst_tag_list_remove_tag:
 750  * @list: list to remove tag from
 751  * @tag: tag to remove
 752  *
 753  * Removes the goven tag from the taglist.
 754  */
 755 void
 756 gst_tag_list_remove_tag (GstTagList * list, const gchar * tag)
 757 {
 758   g_return_if_fail (GST_IS_TAG_LIST (list));
 759   g_return_if_fail (tag != NULL);
 760
 761   gst_structure_remove_field ((GstStructure *) list, tag);
 762 }
 763 typedef struct
 764 {
 765   GstTagForeachFunc func;
 766   GstTagList *tag_list;
 767   gpointer data;
 768 }
 769 TagForeachData;
 770 static int
 771 structure_foreach_wrapper (GQuark field_id, GValue * value, gpointer user_data)
 772 {
 773   TagForeachData *data = (TagForeachData *) user_data;
 774
 775   data->func (data->tag_list, g_quark_to_string (field_id), data->data);
 776   return TRUE;
 777 }
 778
 779 /**
 780  * gst_tag_list_foreach:
 781  * @list: list to iterate over
 782  * @func: function to be called for each tag
 783  * @user_data: user specified data
 784  *
 785  * Calls the given function for each tag inside the tag list. Note that if there
 786  * is no tag, the function won't be called at all.
 787  */
 788 void
 789 gst_tag_list_foreach (GstTagList * list, GstTagForeachFunc func,
 790     gpointer user_data)
 791 {
 792   TagForeachData data;
 793
 794   g_return_if_fail (GST_IS_TAG_LIST (list));
 795   g_return_if_fail (func != NULL);
 796
 797   data.func = func;
 798   data.tag_list = list;
 799   data.data = user_data;
 800   gst_structure_foreach ((GstStructure *) list, structure_foreach_wrapper,
 801       &data);
 802 }
 803
 804 /***** tag events *****/
 805
 806 /**
 807  * gst_event_new_tag:
 808  * @list: the tag list to put into the event or NULL for an empty list
 809  *
 810  * Creates a new tag event with the given list and takes ownership of it.
 811  *
 812  * Returns: a new tag event
 813  */
 814 GstEvent *
 815 gst_event_new_tag (GstTagList * list)
 816 {
 817   GstEvent *ret;
 818
 819   g_return_val_if_fail (list == NULL || GST_IS_TAG_LIST (list), NULL);
 820
 821   ret = gst_event_new (GST_EVENT_TAG);
 822   if (!list)
 823     list = gst_tag_list_new ();
 824   ret->event_data.structure.structure = (GstStructure *) list;
 825
 826   return ret;
 827 }
 828
 829 /**
 830  * get_event_tag_get_list:
 831  * @tag_event: a tagging #GstEvent
 832  *
 833  * Gets the taglist from a given tagging event.
 834  *
 835  * Returns: The #GstTagList of the event
 836  */
 837 GstTagList *
 838 gst_event_tag_get_list (GstEvent * tag_event)
 839 {
 840   g_return_val_if_fail (GST_IS_EVENT (tag_event), NULL);
 841   g_return_val_if_fail (GST_EVENT_TYPE (tag_event) == GST_EVENT_TAG, NULL);
 842
 843   return GST_TAG_LIST (tag_event->event_data.structure.structure);
 844 }
 845
 846 /**
 847  * gst_tag_list_get_value_index:
 848  * @list: a #GStTagList
 849  * @tag: tag to read out
 850  * @index: number of entry to read out
 851  *
 852  * Gets the value that is at the given index for the given tag in the given
 853  * list.
 854  *
 855  * Returns: The GValue for the specified entry or NULL if the tag wasn't available
 856  *          or the tag doesn't have as many entries
 857  */
 858 G_CONST_RETURN GValue *
 859 gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag,
 860     guint index)
 861 {
 862   const GValue *value;
 863
 864   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
 865   g_return_val_if_fail (tag != NULL, NULL);
 866
 867   value = gst_structure_get_value ((GstStructure *) list, tag);
 868   if (value == NULL)
 869     return NULL;
 870
 871   if (GST_VALUE_HOLDS_LIST (value)) {
 872     if (index >= gst_value_list_get_size (value))
 873       return NULL;
 874     return gst_value_list_get_value (value, index);
 875   } else {
 876     if (index > 0)
 877       return NULL;
 878     return value;
 879   }
 880 }
 881
 882 /**
 883  * gst_tag_list_copy_value:
 884  * @dest: uninitialized #GValue to copy into
 885  * @list: list to get the tag from
 886  * @tag: tag to read out
 887  *
 888  * Copies the contents for the given tag into the value, merging multiple values
 889  * into one if multiple values are associated with the tag.
 890  * You must g_value_unset() the value after use.
 891  *
 892  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
 893  *          given list.
 894  */
 895 gboolean
 896 gst_tag_list_copy_value (GValue * dest, const GstTagList * list,
 897     const gchar * tag)
 898 {
 899   const GValue *src;
 900
 901   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
 902   g_return_val_if_fail (tag != NULL, FALSE);
 903   g_return_val_if_fail (dest != NULL, FALSE);
 904   g_return_val_if_fail (G_VALUE_TYPE (dest) == 0, FALSE);
 905
 906   src = gst_structure_get_value ((GstStructure *) list, tag);
 907   if (!src)
 908     return FALSE;
 909
 910   if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
 911     GstTagInfo *info = gst_tag_lookup (g_quark_from_string (tag));
 912
 913     /* must be there or lists aren't allowed */
 914     g_assert (info->merge_func);
 915     info->merge_func (dest, src);
 916   } else {
 917     g_value_init (dest, G_VALUE_TYPE (src));
 918     g_value_copy (src, dest);
 919   }
 920   return TRUE;
 921 }
 922
 923 /***** evil macros to get all the gst_tag_list_get_*() functions right *****/
 924
 925 #define TAG_MERGE_FUNCS(name,type)                                              \
 926 gboolean                                                                        \
 927 gst_tag_list_get_ ## name (const GstTagList *list, const gchar *tag,            \
 928                            type *value)                                         \
 929 {                                                                               \
 930   GValue v = { 0, };                                                            \
 931                                                                                 \
 932   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                         \
 933   g_return_val_if_fail (tag != NULL, FALSE);                                    \
 934   g_return_val_if_fail (value != NULL, FALSE);                                  \
 935                                                                                 \
 936   if (!gst_tag_list_copy_value (&v, list, tag))                                 \
 937       return FALSE;                                                             \
 938   *value = COPY_FUNC (g_value_get_ ## name (&v));                               \
 939   g_value_unset (&v);                                                           \
 940   return TRUE;                                                                  \
 941 }                                                                               \
 942                                                                                 \
 943 gboolean                                                                        \
 944 gst_tag_list_get_ ## name ## _index (const GstTagList *list, const gchar *tag,  \
 945                            guint index, type *value)                            \
 946 {                                                                               \
 947   const GValue *v;                                                              \
 948                                                                                 \
 949   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                         \
 950   g_return_val_if_fail (tag != NULL, FALSE);                                    \
 951   g_return_val_if_fail (value != NULL, FALSE);                                  \
 952                                                                                 \
 953   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)            \
 954       return FALSE;                                                             \
 955   *value = COPY_FUNC (g_value_get_ ## name (v));                                \
 956   return TRUE;                                                                  \
 957 }
 958
 959 #define COPY_FUNC /**/
 960 TAG_MERGE_FUNCS (char, gchar)
 961 TAG_MERGE_FUNCS (uchar, guchar)
 962 TAG_MERGE_FUNCS (boolean, gboolean)
 963 TAG_MERGE_FUNCS (int, gint)
 964 TAG_MERGE_FUNCS (uint, guint)
 965 TAG_MERGE_FUNCS (long, glong)
 966 TAG_MERGE_FUNCS (ulong, gulong)
 967 TAG_MERGE_FUNCS (int64, gint64)
 968 TAG_MERGE_FUNCS (uint64, guint64)
 969 TAG_MERGE_FUNCS (float, gfloat)
 970 TAG_MERGE_FUNCS (double, gdouble)
 971 #undef COPY_FUNC
 972 #define COPY_FUNC g_strdup
 973 TAG_MERGE_FUNCS (string, gchar *)