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