merge in tagging
[platform/upstream/gstreamer.git] / 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_STRING,
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_take_string (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_VALUE_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   GstStructureField *field;
394   
395   g_assert (info != NULL);
396
397   if (info->merge_func && (field = gst_structure_id_get_field (list, tag)) != NULL) {
398     GValue value2 = { 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 (&value2, value, &field->value);
406         gst_structure_id_set_value (list, tag, &value2);
407         g_value_unset (&value2);
408         break;
409       case GST_TAG_MERGE_APPEND:
410         gst_value_list_concat (&value2, &field->value, value);
411         gst_structure_id_set_value (list, tag, &value2);
412         g_value_unset (&value2);
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_field (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 void
442 gst_tag_list_copy_foreach (GstStructure *structure, 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 /**
449  * gst_tag_list_insert:
450  * @into: list to merge into
451  * @from: list to merge from
452  * @mode: the mode to use
453  * 
454  * Inserts the tags of the second list into the first list using the given mode.
455  */
456 void
457 gst_tag_list_insert (GstTagList *into, const GstTagList *from, GstTagMergeMode mode)
458 {
459   GstTagCopyData data;
460   
461   g_return_if_fail (GST_IS_TAG_LIST (into));
462   g_return_if_fail (GST_IS_TAG_LIST (from));
463   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
464
465   data.list = (GstStructure *) into;
466   data.mode = mode;
467   if (mode == GST_TAG_MERGE_REPLACE_ALL) {
468     gst_structure_remove_all_fields (data.list);
469   }
470   gst_structure_field_foreach ((GstStructure *) from, gst_tag_list_copy_foreach, &data);
471 }
472 /**
473  * gst_tag_list_copy:
474  * @list: list to copy
475  *
476  * Copies a given #GstTagList.
477  *
478  * Returns: copy of the given list
479  */
480 GstTagList *
481 gst_tag_list_copy (const GstTagList *list)
482 {
483   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
484   
485   return GST_TAG_LIST (gst_structure_copy ((GstStructure *) list));
486 }
487 /**
488  * gst_tag_list_merge:
489  * @list1: first list to merge
490  * @list2: second list to merge
491  * @mode: the mode to use
492  * 
493  * Merges the two given lists into a new list. If one of the lists is NULL, a
494  * copy of the other is returned. If both lists are NULL, NULL is returned.
495  *
496  * Returns: the new list
497  */
498 GstTagList *
499 gst_tag_list_merge (const GstTagList *list1, const GstTagList *list2, GstTagMergeMode mode)
500 {
501   g_return_val_if_fail (list1 == NULL || GST_IS_TAG_LIST (list1), NULL);
502   g_return_val_if_fail (list2 == NULL || GST_IS_TAG_LIST (list2), NULL);
503   g_return_val_if_fail (GST_TAG_MODE_IS_VALID (mode), NULL);
504
505   if (!list1 && !list2) {
506     return NULL;
507   } else if (!list1) {
508     return gst_tag_list_copy (list2);
509   } else if (!list2) {
510     return gst_tag_list_copy (list1);
511   } else {
512     GstTagList *ret;
513
514     ret = gst_tag_list_copy (list1);
515     gst_tag_list_insert (ret, list2, mode);
516     return ret;
517   }
518 }
519 /**
520  * gst_tag_list_free:
521  * @list: the list to free
522  *
523  * Frees the given list and all associated values.
524  */
525 void
526 gst_tag_list_free (GstTagList *list)
527 {
528   g_return_if_fail (GST_IS_TAG_LIST (list));
529   gst_structure_free ((GstStructure *) list);
530 }
531 /**
532  * gst_tag_list_get_tag_size:
533  * @list: a taglist
534  * @tag: the tag to query
535  *
536  * Checks how many value are stored in this tag list for the given tag.
537  *
538  * Returns: The number of tags stored
539  */
540 guint
541 gst_tag_list_get_tag_size (const GstTagList *list, const gchar *tag)
542 {
543   const GValue *value;
544
545   g_return_val_if_fail (GST_IS_TAG_LIST (list), 0);
546
547   value = gst_structure_get_value ((GstStructure *) list, tag);
548   if (value == NULL)
549     return 0;
550   if (G_VALUE_TYPE (value) != GST_VALUE_TYPE_LIST)
551     return 1;
552
553   return gst_value_list_get_size (value);
554 }
555 /**
556  * gst_tag_list_add:
557  * @list: list to set tags in
558  * @mode: the mode to use
559  * @tag: tag
560  * @...: values to set
561  *
562  * Sets the values for the given tags using the specified mode.
563  */
564 void
565 gst_tag_list_add (GstTagList *list, GstTagMergeMode mode, const gchar *tag, ...)
566 {
567   va_list args;
568
569   g_return_if_fail (GST_IS_TAG_LIST (list));
570   g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
571   g_return_if_fail (tag != NULL);
572   
573   va_start (args, tag);
574   gst_tag_list_add_valist (list, mode, tag, args);
575   va_end (args);
576 }
577 /**
578  * gst_tag_list_add_valist:
579  * @list: list to set tags in
580  * @mode: the mode to use
581  * @tag: tag
582  * @var_args: tag / value pairs to set
583  *
584  * Sets the values for the given tags using the specified mode.
585  */
586 void
587 gst_tag_list_add_valist (GstTagList *list, GstTagMergeMode mode, const gchar *tag, va_list var_args)
588 {
589   GstTagInfo *info;
590   GQuark quark;
591   gchar *error = NULL;
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   while (tag != NULL) {
598     GValue value = { 0, };
599     quark = g_quark_from_string (tag);
600     info = gst_tag_lookup (quark);
601     g_return_if_fail (info != NULL);
602     g_value_init (&value, info->type);
603     G_VALUE_COLLECT (&value, var_args, 0, &error);
604     if (error) {
605       g_warning ("%s: %s", G_STRLOC, error);
606       g_free (error);
607       /* we purposely leak the value here, it might not be
608        * in a sane state if an error condition occoured
609        */
610       return;
611     }
612     gst_tag_list_add_value_internal (list, mode, quark, &value);
613     g_value_unset (&value);
614     tag = va_arg (var_args, gchar *);
615   }
616 }
617 /**
618  * gst_tag_list_remove_tag:
619  * @list: list to remove tag from
620  * @tag: tag to remove
621  *
622  * Removes the goven tag from the taglist.
623  */
624 void
625 gst_tag_list_remove_tag (GstTagList *list, const gchar *tag)
626 {
627   g_return_if_fail (GST_IS_TAG_LIST (list));
628   g_return_if_fail (tag != NULL);
629
630   gst_structure_remove_field ((GstStructure *) list, tag);
631 }
632 typedef struct {
633   GstTagForeachFunc     func;
634   gpointer              data;
635 } TagForeachData;
636 static void 
637 structure_foreach_wrapper (GstStructure *structure, GQuark field_id, 
638         GValue *value, gpointer user_data)
639 {
640   TagForeachData *data = (TagForeachData *) user_data;
641   data->func (GST_TAG_LIST (structure), g_quark_to_string (field_id), data->data);
642 }
643 /**
644  * gst_tag_list_foreach:
645  * @list: list to iterate over
646  * @func: function to be called for each tag
647  * @user_data: user specified data
648  *
649  * Calls the given function for each tag inside the tag list. Note that if there
650  * is no tag, the function won't be called at all.
651  */
652 void
653 gst_tag_list_foreach (GstTagList *list, GstTagForeachFunc func, gpointer user_data)
654 {
655   TagForeachData data;
656
657   g_return_if_fail (GST_IS_TAG_LIST (list));
658   g_return_if_fail (func != NULL);
659   
660   data.func = func;
661   data.data = user_data;
662   gst_structure_field_foreach ((GstStructure *) list, structure_foreach_wrapper, &data);
663 }
664
665 /***** tag events *****/
666
667 /**
668  * gst_event_new_tag:
669  * @list: the tag list to put into the event or NULL for an empty list
670  *
671  * Creates a new tag event with the given list and takes ownership of it.
672  *
673  * Returns: a new tag event
674  */
675 GstEvent *
676 gst_event_new_tag (GstTagList *list)
677 {
678   GstEvent *ret;
679   
680   g_return_val_if_fail (list == NULL || GST_IS_TAG_LIST (list), NULL);
681
682   ret = gst_event_new (GST_EVENT_TAG);
683   if (!list)
684     list = gst_tag_list_new ();
685   ret->event_data.structure.structure = (GstStructure *) list;
686   
687   return ret;
688 }
689 /**
690  * get_event_tag_get_list:
691  * @tag_event: a tagging #GstEvent
692  *
693  * Gets the taglist from a given tagging event.
694  * 
695  * Returns: The #GstTagList of the event
696  */
697 GstTagList *
698 gst_event_tag_get_list (GstEvent *tag_event)
699 {
700   g_return_val_if_fail (GST_IS_EVENT (tag_event), NULL);
701   g_return_val_if_fail (GST_EVENT_TYPE (tag_event) == GST_EVENT_TAG, NULL);
702
703   return GST_TAG_LIST (tag_event->event_data.structure.structure);
704 }
705
706 /**
707  * gst_tag_list_get_value_index:
708  * @list: a #GStTagList
709  * @tag: tag to read out
710  * @index: number of entry to read out
711  *
712  * Gets the value that is at the given index for the given tag in the given 
713  * list.
714  * 
715  * Returns: The GValue for the specified entry or NULL if the tag wasn't available
716  *          or the tag doesn't have as many entries
717  */
718 G_CONST_RETURN GValue *
719 gst_tag_list_get_value_index (const GstTagList *list, const gchar *tag, guint index)
720 {
721   const GValue *value;
722
723   g_return_val_if_fail (GST_IS_TAG_LIST (list), NULL);
724   g_return_val_if_fail (tag != NULL, NULL);
725   
726   value = gst_structure_get_value ((GstStructure *) list, tag);
727   if (value == NULL) return  NULL;
728   
729   if (GST_VALUE_HOLDS_LIST (value)) {
730     if (index >= gst_value_list_get_size (value)) return NULL;
731     return gst_value_list_get_value (value, index);
732   } else {
733     if (index > 0) return NULL;
734     return value;
735   }
736 }
737
738 /**
739  * gst_tag_list_copy_value:
740  * @dest: uninitialized #GValue to copy into
741  * @list: list to get the tag from
742  * @tag: tag to read out
743  *
744  * Copies the contents for the given tag into the value, merging multiple values 
745  * into one if multiple values are associated with the tag.
746  * You must g_value_unset() the value after use.
747  *
748  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the 
749  *          given list.
750  */
751 gboolean
752 gst_tag_list_copy_value (GValue *dest, const GstTagList *list, const gchar *tag)
753 {
754   const GValue *src;
755   
756   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
757   g_return_val_if_fail (tag != NULL, FALSE);
758   g_return_val_if_fail (dest != NULL, FALSE);
759   g_return_val_if_fail (G_VALUE_TYPE (dest) == 0, FALSE);
760   
761   src = gst_structure_get_value ((GstStructure *) list, tag);
762   if (!src) return FALSE;
763   
764   if (G_VALUE_TYPE (src) == GST_VALUE_TYPE_LIST) {    
765     GstTagInfo *info = gst_tag_lookup (g_quark_from_string (tag));
766     /* must be there or lists aren't allowed */
767     g_assert (info->merge_func);
768     info->merge_func (dest, src);
769   } else {
770     g_value_init (dest, G_VALUE_TYPE (src));
771     g_value_copy (src, dest);
772   }
773   return TRUE;
774 }
775
776 /***** evil macros to get all the gst_tag_list_get_*() functions right *****/
777
778 #define TAG_MERGE_FUNCS(name,type)                                              \
779 gboolean                                                                        \
780 gst_tag_list_get_ ## name (const GstTagList *list, const gchar *tag,            \
781                            type *value)                                         \
782 {                                                                               \
783   GValue v = { 0, };                                                            \
784                                                                                 \
785   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                         \
786   g_return_val_if_fail (tag != NULL, FALSE);                                    \
787   g_return_val_if_fail (value != NULL, FALSE);                                  \
788                                                                                 \
789   if (!gst_tag_list_copy_value (&v, list, tag))                                 \
790       return FALSE;                                                             \
791   *value = COPY_FUNC (g_value_get_ ## name (&v));                               \
792   g_value_unset (&v);                                                           \
793   return TRUE;                                                                  \
794 }                                                                               \
795                                                                                 \
796 gboolean                                                                        \
797 gst_tag_list_get_ ## name ## _index (const GstTagList *list, const gchar *tag,  \
798                            guint index, type *value)                            \
799 {                                                                               \
800   const GValue *v;                                                              \
801                                                                                 \
802   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);                         \
803   g_return_val_if_fail (tag != NULL, FALSE);                                    \
804   g_return_val_if_fail (value != NULL, FALSE);                                  \
805                                                                                 \
806   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)            \
807       return FALSE;                                                             \
808   *value = COPY_FUNC (g_value_get_ ## name (v));                                \
809   return TRUE;                                                                  \
810 }
811
812 #define COPY_FUNC /**/
813 TAG_MERGE_FUNCS (char, gchar)
814 TAG_MERGE_FUNCS (uchar, guchar)
815 TAG_MERGE_FUNCS (boolean, gboolean)
816 TAG_MERGE_FUNCS (int, gint)
817 TAG_MERGE_FUNCS (uint, guint)
818 TAG_MERGE_FUNCS (long, glong)
819 TAG_MERGE_FUNCS (ulong, gulong)
820 TAG_MERGE_FUNCS (int64, gint64)
821 TAG_MERGE_FUNCS (uint64, guint64)
822 TAG_MERGE_FUNCS (float, gfloat)
823 TAG_MERGE_FUNCS (double, gdouble)
824 #undef COPY_FUNC
825   
826 #define COPY_FUNC g_strdup
827 TAG_MERGE_FUNCS (string, gchar *)
828
829
830
831