tracerrecord: allow G_TYPE_POINTER for field types
[platform/upstream/gstreamer.git] / gst / gststructure.c
1 /* GStreamer
2  * Copyright (C) 2003 David A. Schleef <ds@schleef.org>
3  *
4  * gststructure.c: lists of { GQuark, GValue } tuples
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Library General Public License for more details.
15  *
16  * You should have received a copy of the GNU Library General Public
17  * License along with this library; if not, write to the
18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19  * Boston, MA 02110-1301, USA.
20  */
21
22 /**
23  * SECTION:gststructure
24  * @short_description: Generic structure containing fields of names and values
25  * @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery
26  *
27  * A #GstStructure is a collection of key/value pairs. The keys are expressed
28  * as GQuarks and the values can be of any GType.
29  *
30  * In addition to the key/value pairs, a #GstStructure also has a name. The name
31  * starts with a letter and can be filled by letters, numbers and any of "/-_.:".
32  *
33  * #GstStructure is used by various GStreamer subsystems to store information
34  * in a flexible and extensible way. A #GstStructure does not have a refcount
35  * because it usually is part of a higher level object such as #GstCaps,
36  * #GstMessage, #GstEvent, #GstQuery. It provides a means to enforce mutability
37  * using the refcount of the parent with the gst_structure_set_parent_refcount()
38  * method.
39  *
40  * A #GstStructure can be created with gst_structure_new_empty() or
41  * gst_structure_new(), which both take a name and an optional set of
42  * key/value pairs along with the types of the values.
43  *
44  * Field values can be changed with gst_structure_set_value() or
45  * gst_structure_set().
46  *
47  * Field values can be retrieved with gst_structure_get_value() or the more
48  * convenient gst_structure_get_*() functions.
49  *
50  * Fields can be removed with gst_structure_remove_field() or
51  * gst_structure_remove_fields().
52  *
53  * Strings in structures must be ASCII or UTF-8 encoded. Other encodings are
54  * not allowed. Strings may be %NULL however.
55  *
56  * Be aware that the current #GstCaps / #GstStructure serialization into string
57  * has limited support for nested #GstCaps / #GstStructure fields. It can only
58  * support one level of nesting. Using more levels will lead to unexpected
59  * behavior when using serialization features, such as gst_caps_to_string() or
60  * gst_value_serialize() and their counterparts.
61  */
62
63 #ifdef HAVE_CONFIG_H
64 #include "config.h"
65 #endif
66
67 #include <string.h>
68
69 #include "gst_private.h"
70 #include "gstquark.h"
71 #include <gst/gst.h>
72 #include <gobject/gvaluecollector.h>
73
74 GST_DEBUG_CATEGORY_STATIC (gst_structure_debug);
75 #define GST_CAT_DEFAULT gst_structure_debug
76
77 typedef struct _GstStructureField GstStructureField;
78
79 struct _GstStructureField
80 {
81   GQuark name;
82   GValue value;
83 };
84
85 typedef struct
86 {
87   GstStructure s;
88
89   /* owned by parent structure, NULL if no parent */
90   gint *parent_refcount;
91
92   GArray *fields;
93 } GstStructureImpl;
94
95 #define GST_STRUCTURE_REFCOUNT(s) (((GstStructureImpl*)(s))->parent_refcount)
96 #define GST_STRUCTURE_FIELDS(s) (((GstStructureImpl*)(s))->fields)
97
98 #define GST_STRUCTURE_FIELD(structure, index) \
99     &g_array_index(GST_STRUCTURE_FIELDS(structure), GstStructureField, (index))
100
101 #define IS_MUTABLE(structure) \
102     (!GST_STRUCTURE_REFCOUNT(structure) || \
103      g_atomic_int_get (GST_STRUCTURE_REFCOUNT(structure)) == 1)
104
105 #define IS_TAGLIST(structure) \
106     (structure->name == GST_QUARK (TAGLIST))
107
108 static void gst_structure_set_field (GstStructure * structure,
109     GstStructureField * field);
110 static GstStructureField *gst_structure_get_field (const GstStructure *
111     structure, const gchar * fieldname);
112 static GstStructureField *gst_structure_id_get_field (const GstStructure *
113     structure, GQuark field);
114 static void gst_structure_transform_to_string (const GValue * src_value,
115     GValue * dest_value);
116 static GstStructure *gst_structure_copy_conditional (const GstStructure *
117     structure);
118 static gboolean gst_structure_parse_value (gchar * str, gchar ** after,
119     GValue * value, GType default_type);
120 static gboolean gst_structure_parse_simple_string (gchar * s, gchar ** end);
121
122 GType _gst_structure_type = 0;
123
124
125 G_DEFINE_BOXED_TYPE (GstStructure, gst_structure,
126     gst_structure_copy_conditional, gst_structure_free);
127
128 void
129 _priv_gst_structure_initialize (void)
130 {
131   _gst_structure_type = gst_structure_get_type ();
132
133   g_value_register_transform_func (_gst_structure_type, G_TYPE_STRING,
134       gst_structure_transform_to_string);
135
136   GST_DEBUG_CATEGORY_INIT (gst_structure_debug, "structure", 0,
137       "GstStructure debug");
138 }
139
140 static GstStructure *
141 gst_structure_new_id_empty_with_size (GQuark quark, guint prealloc)
142 {
143   GstStructureImpl *structure;
144
145   structure = g_slice_new (GstStructureImpl);
146   ((GstStructure *) structure)->type = _gst_structure_type;
147   ((GstStructure *) structure)->name = quark;
148   GST_STRUCTURE_REFCOUNT (structure) = NULL;
149   GST_STRUCTURE_FIELDS (structure) =
150       g_array_sized_new (FALSE, FALSE, sizeof (GstStructureField), prealloc);
151
152   GST_TRACE ("created structure %p", structure);
153
154   return GST_STRUCTURE_CAST (structure);
155 }
156
157 /**
158  * gst_structure_new_id_empty:
159  * @quark: name of new structure
160  *
161  * Creates a new, empty #GstStructure with the given name as a GQuark.
162  *
163  * Free-function: gst_structure_free
164  *
165  * Returns: (transfer full): a new, empty #GstStructure
166  */
167 GstStructure *
168 gst_structure_new_id_empty (GQuark quark)
169 {
170   g_return_val_if_fail (quark != 0, NULL);
171
172   return gst_structure_new_id_empty_with_size (quark, 0);
173 }
174
175 #ifndef G_DISABLE_CHECKS
176 static gboolean
177 gst_structure_validate_name (const gchar * name)
178 {
179   const gchar *s;
180
181   g_return_val_if_fail (name != NULL, FALSE);
182
183   if (G_UNLIKELY (!g_ascii_isalpha (*name))) {
184     GST_WARNING ("Invalid character '%c' at offset 0 in structure name: %s",
185         *name, name);
186     return FALSE;
187   }
188
189   /* FIXME: test name string more */
190   s = &name[1];
191   while (*s && (g_ascii_isalnum (*s) || strchr ("/-_.:+", *s) != NULL))
192     s++;
193   if (G_UNLIKELY (*s != '\0')) {
194     GST_WARNING ("Invalid character '%c' at offset %" G_GUINTPTR_FORMAT " in"
195         " structure name: %s", *s, ((guintptr) s - (guintptr) name), name);
196     return FALSE;
197   }
198
199   if (strncmp (name, "video/x-raw-", 12) == 0) {
200     g_warning ("0.10-style raw video caps are being created. Should be "
201         "video/x-raw,format=(string).. now.");
202   } else if (strncmp (name, "audio/x-raw-", 12) == 0) {
203     g_warning ("0.10-style raw audio caps are being created. Should be "
204         "audio/x-raw,format=(string).. now.");
205   }
206
207   return TRUE;
208 }
209 #endif
210
211 /**
212  * gst_structure_new_empty:
213  * @name: name of new structure
214  *
215  * Creates a new, empty #GstStructure with the given @name.
216  *
217  * See gst_structure_set_name() for constraints on the @name parameter.
218  *
219  * Free-function: gst_structure_free
220  *
221  * Returns: (transfer full): a new, empty #GstStructure
222  */
223 GstStructure *
224 gst_structure_new_empty (const gchar * name)
225 {
226   g_return_val_if_fail (gst_structure_validate_name (name), NULL);
227
228   return gst_structure_new_id_empty_with_size (g_quark_from_string (name), 0);
229 }
230
231 /**
232  * gst_structure_new:
233  * @name: name of new structure
234  * @firstfield: name of first field to set
235  * @...: additional arguments
236  *
237  * Creates a new #GstStructure with the given name.  Parses the
238  * list of variable arguments and sets fields to the values listed.
239  * Variable arguments should be passed as field name, field type,
240  * and value.  Last variable argument should be %NULL.
241  *
242  * Free-function: gst_structure_free
243  *
244  * Returns: (transfer full): a new #GstStructure
245  */
246 GstStructure *
247 gst_structure_new (const gchar * name, const gchar * firstfield, ...)
248 {
249   GstStructure *structure;
250   va_list varargs;
251
252   va_start (varargs, firstfield);
253   structure = gst_structure_new_valist (name, firstfield, varargs);
254   va_end (varargs);
255
256   return structure;
257 }
258
259 /**
260  * gst_structure_new_valist:
261  * @name: name of new structure
262  * @firstfield: name of first field to set
263  * @varargs: variable argument list
264  *
265  * Creates a new #GstStructure with the given @name.  Structure fields
266  * are set according to the varargs in a manner similar to
267  * gst_structure_new().
268  *
269  * See gst_structure_set_name() for constraints on the @name parameter.
270  *
271  * Free-function: gst_structure_free
272  *
273  * Returns: (transfer full): a new #GstStructure
274  */
275 GstStructure *
276 gst_structure_new_valist (const gchar * name,
277     const gchar * firstfield, va_list varargs)
278 {
279   GstStructure *structure;
280
281   structure = gst_structure_new_empty (name);
282
283   if (structure)
284     gst_structure_set_valist (structure, firstfield, varargs);
285
286   return structure;
287 }
288
289 /**
290  * gst_structure_set_parent_refcount:
291  * @structure: a #GstStructure
292  * @refcount: (in): a pointer to the parent's refcount
293  *
294  * Sets the parent_refcount field of #GstStructure. This field is used to
295  * determine whether a structure is mutable or not. This function should only be
296  * called by code implementing parent objects of #GstStructure, as described in
297  * the MT Refcounting section of the design documents.
298  *
299  * Returns: %TRUE if the parent refcount could be set.
300  */
301 gboolean
302 gst_structure_set_parent_refcount (GstStructure * structure, gint * refcount)
303 {
304   g_return_val_if_fail (structure != NULL, FALSE);
305
306   /* if we have a parent_refcount already, we can only clear
307    * if with a NULL refcount */
308   if (GST_STRUCTURE_REFCOUNT (structure)) {
309     if (refcount != NULL) {
310       g_return_val_if_fail (refcount == NULL, FALSE);
311       return FALSE;
312     }
313   } else {
314     if (refcount == NULL) {
315       g_return_val_if_fail (refcount != NULL, FALSE);
316       return FALSE;
317     }
318   }
319
320   GST_STRUCTURE_REFCOUNT (structure) = refcount;
321
322   return TRUE;
323 }
324
325 /**
326  * gst_structure_copy:
327  * @structure: a #GstStructure to duplicate
328  *
329  * Duplicates a #GstStructure and all its fields and values.
330  *
331  * Free-function: gst_structure_free
332  *
333  * Returns: (transfer full): a new #GstStructure.
334  */
335 GstStructure *
336 gst_structure_copy (const GstStructure * structure)
337 {
338   GstStructure *new_structure;
339   GstStructureField *field;
340   guint i, len;
341
342   g_return_val_if_fail (structure != NULL, NULL);
343
344   len = GST_STRUCTURE_FIELDS (structure)->len;
345   new_structure = gst_structure_new_id_empty_with_size (structure->name, len);
346
347   for (i = 0; i < len; i++) {
348     GstStructureField new_field = { 0 };
349
350     field = GST_STRUCTURE_FIELD (structure, i);
351
352     new_field.name = field->name;
353     gst_value_init_and_copy (&new_field.value, &field->value);
354     g_array_append_val (GST_STRUCTURE_FIELDS (new_structure), new_field);
355   }
356   GST_CAT_TRACE (GST_CAT_PERFORMANCE, "doing copy %p -> %p",
357       structure, new_structure);
358
359   return new_structure;
360 }
361
362 /**
363  * gst_structure_free:
364  * @structure: (in) (transfer full): the #GstStructure to free
365  *
366  * Frees a #GstStructure and all its fields and values. The structure must not
367  * have a parent when this function is called.
368  */
369 void
370 gst_structure_free (GstStructure * structure)
371 {
372   GstStructureField *field;
373   guint i, len;
374
375   g_return_if_fail (structure != NULL);
376   g_return_if_fail (GST_STRUCTURE_REFCOUNT (structure) == NULL);
377
378   len = GST_STRUCTURE_FIELDS (structure)->len;
379   for (i = 0; i < len; i++) {
380     field = GST_STRUCTURE_FIELD (structure, i);
381
382     if (G_IS_VALUE (&field->value)) {
383       g_value_unset (&field->value);
384     }
385   }
386   g_array_free (GST_STRUCTURE_FIELDS (structure), TRUE);
387 #ifdef USE_POISONING
388   memset (structure, 0xff, sizeof (GstStructure));
389 #endif
390   GST_TRACE ("free structure %p", structure);
391
392   g_slice_free1 (sizeof (GstStructureImpl), structure);
393 }
394
395 /**
396  * gst_structure_get_name:
397  * @structure: a #GstStructure
398  *
399  * Get the name of @structure as a string.
400  *
401  * Returns: the name of the structure.
402  */
403 const gchar *
404 gst_structure_get_name (const GstStructure * structure)
405 {
406   g_return_val_if_fail (structure != NULL, NULL);
407
408   return g_quark_to_string (structure->name);
409 }
410
411 /**
412  * gst_structure_has_name:
413  * @structure: a #GstStructure
414  * @name: structure name to check for
415  *
416  * Checks if the structure has the given name
417  *
418  * Returns: %TRUE if @name matches the name of the structure.
419  */
420 gboolean
421 gst_structure_has_name (const GstStructure * structure, const gchar * name)
422 {
423   const gchar *structure_name;
424
425   g_return_val_if_fail (structure != NULL, FALSE);
426   g_return_val_if_fail (name != NULL, FALSE);
427
428   /* getting the string is cheap and comparing short strings is too
429    * should be faster than getting the quark for name and comparing the quarks
430    */
431   structure_name = g_quark_to_string (structure->name);
432
433   return (structure_name && strcmp (structure_name, name) == 0);
434 }
435
436 /**
437  * gst_structure_get_name_id:
438  * @structure: a #GstStructure
439  *
440  * Get the name of @structure as a GQuark.
441  *
442  * Returns: the quark representing the name of the structure.
443  */
444 GQuark
445 gst_structure_get_name_id (const GstStructure * structure)
446 {
447   g_return_val_if_fail (structure != NULL, 0);
448
449   return structure->name;
450 }
451
452 /**
453  * gst_structure_set_name:
454  * @structure: a #GstStructure
455  * @name: the new name of the structure
456  *
457  * Sets the name of the structure to the given @name.  The string
458  * provided is copied before being used. It must not be empty, start with a
459  * letter and can be followed by letters, numbers and any of "/-_.:".
460  */
461 void
462 gst_structure_set_name (GstStructure * structure, const gchar * name)
463 {
464   g_return_if_fail (structure != NULL);
465   g_return_if_fail (IS_MUTABLE (structure));
466   g_return_if_fail (gst_structure_validate_name (name));
467
468   structure->name = g_quark_from_string (name);
469 }
470
471 static inline void
472 gst_structure_id_set_value_internal (GstStructure * structure, GQuark field,
473     const GValue * value)
474 {
475   GstStructureField gsfield = { 0, {0,} };
476
477   gsfield.name = field;
478   gst_value_init_and_copy (&gsfield.value, value);
479
480   gst_structure_set_field (structure, &gsfield);
481 }
482
483 /**
484  * gst_structure_id_set_value:
485  * @structure: a #GstStructure
486  * @field: a #GQuark representing a field
487  * @value: the new value of the field
488  *
489  * Sets the field with the given GQuark @field to @value.  If the field
490  * does not exist, it is created.  If the field exists, the previous
491  * value is replaced and freed.
492  */
493 void
494 gst_structure_id_set_value (GstStructure * structure,
495     GQuark field, const GValue * value)
496 {
497
498   g_return_if_fail (structure != NULL);
499   g_return_if_fail (G_IS_VALUE (value));
500   g_return_if_fail (IS_MUTABLE (structure));
501
502   gst_structure_id_set_value_internal (structure, field, value);
503 }
504
505 /**
506  * gst_structure_set_value:
507  * @structure: a #GstStructure
508  * @fieldname: the name of the field to set
509  * @value: the new value of the field
510  *
511  * Sets the field with the given name @field to @value.  If the field
512  * does not exist, it is created.  If the field exists, the previous
513  * value is replaced and freed.
514  */
515 void
516 gst_structure_set_value (GstStructure * structure,
517     const gchar * fieldname, const GValue * value)
518 {
519   g_return_if_fail (structure != NULL);
520   g_return_if_fail (fieldname != NULL);
521   g_return_if_fail (G_IS_VALUE (value));
522   g_return_if_fail (IS_MUTABLE (structure));
523
524   gst_structure_id_set_value_internal (structure,
525       g_quark_from_string (fieldname), value);
526 }
527
528 static inline void
529 gst_structure_id_take_value_internal (GstStructure * structure, GQuark field,
530     GValue * value)
531 {
532   GstStructureField gsfield = { 0, {0,} };
533
534   gsfield.name = field;
535   gsfield.value = *value;
536
537   gst_structure_set_field (structure, &gsfield);
538
539   /* we took ownership */
540 #ifdef USE_POISONING
541   memset (value, 0, sizeof (GValue));
542 #else
543   value->g_type = G_TYPE_INVALID;
544 #endif
545 }
546
547 /**
548  * gst_structure_id_take_value:
549  * @structure: a #GstStructure
550  * @field: a #GQuark representing a field
551  * @value: (transfer full): the new value of the field
552  *
553  * Sets the field with the given GQuark @field to @value.  If the field
554  * does not exist, it is created.  If the field exists, the previous
555  * value is replaced and freed.
556  */
557 void
558 gst_structure_id_take_value (GstStructure * structure, GQuark field,
559     GValue * value)
560 {
561   g_return_if_fail (structure != NULL);
562   g_return_if_fail (G_IS_VALUE (value));
563   g_return_if_fail (IS_MUTABLE (structure));
564
565   gst_structure_id_take_value_internal (structure, field, value);
566 }
567
568 /**
569  * gst_structure_take_value:
570  * @structure: a #GstStructure
571  * @fieldname: the name of the field to set
572  * @value: (transfer full): the new value of the field
573  *
574  * Sets the field with the given name @field to @value.  If the field
575  * does not exist, it is created.  If the field exists, the previous
576  * value is replaced and freed. The function will take ownership of @value.
577  */
578 void
579 gst_structure_take_value (GstStructure * structure, const gchar * fieldname,
580     GValue * value)
581 {
582   g_return_if_fail (structure != NULL);
583   g_return_if_fail (fieldname != NULL);
584   g_return_if_fail (G_IS_VALUE (value));
585   g_return_if_fail (IS_MUTABLE (structure));
586
587   gst_structure_id_take_value_internal (structure,
588       g_quark_from_string (fieldname), value);
589 }
590
591 static void
592 gst_structure_set_valist_internal (GstStructure * structure,
593     const gchar * fieldname, va_list varargs)
594 {
595   gchar *err = NULL;
596   GType type;
597
598   while (fieldname) {
599     GstStructureField field = { 0 };
600
601     field.name = g_quark_from_string (fieldname);
602
603     type = va_arg (varargs, GType);
604
605     G_VALUE_COLLECT_INIT (&field.value, type, varargs, 0, &err);
606     if (G_UNLIKELY (err)) {
607       g_critical ("%s", err);
608       return;
609     }
610     gst_structure_set_field (structure, &field);
611
612     fieldname = va_arg (varargs, gchar *);
613   }
614 }
615
616 /**
617  * gst_structure_set:
618  * @structure: a #GstStructure
619  * @fieldname: the name of the field to set
620  * @...: variable arguments
621  *
622  * Parses the variable arguments and sets fields accordingly. Fields that
623  * weren't already part of the structure are added as needed.
624  * Variable arguments should be in the form field name, field type
625  * (as a GType), value(s).  The last variable argument should be %NULL.
626  */
627 void
628 gst_structure_set (GstStructure * structure, const gchar * field, ...)
629 {
630   va_list varargs;
631
632   g_return_if_fail (structure != NULL);
633   g_return_if_fail (IS_MUTABLE (structure) || field == NULL);
634
635   va_start (varargs, field);
636   gst_structure_set_valist_internal (structure, field, varargs);
637   va_end (varargs);
638 }
639
640 /**
641  * gst_structure_set_valist:
642  * @structure: a #GstStructure
643  * @fieldname: the name of the field to set
644  * @varargs: variable arguments
645  *
646  * va_list form of gst_structure_set().
647  */
648 void
649 gst_structure_set_valist (GstStructure * structure,
650     const gchar * fieldname, va_list varargs)
651 {
652   g_return_if_fail (structure != NULL);
653   g_return_if_fail (IS_MUTABLE (structure));
654
655   gst_structure_set_valist_internal (structure, fieldname, varargs);
656 }
657
658 static void
659 gst_structure_id_set_valist_internal (GstStructure * structure,
660     GQuark fieldname, va_list varargs)
661 {
662   gchar *err = NULL;
663   GType type;
664
665   while (fieldname) {
666     GstStructureField field = { 0 };
667
668     field.name = fieldname;
669     type = va_arg (varargs, GType);
670
671     G_VALUE_COLLECT_INIT (&field.value, type, varargs, 0, &err);
672     if (G_UNLIKELY (err)) {
673       g_critical ("%s", err);
674       return;
675     }
676     gst_structure_set_field (structure, &field);
677
678     fieldname = va_arg (varargs, GQuark);
679   }
680 }
681
682 /**
683  * gst_structure_id_set:
684  * @structure: a #GstStructure
685  * @fieldname: the GQuark for the name of the field to set
686  * @...: variable arguments
687  *
688  * Identical to gst_structure_set, except that field names are
689  * passed using the GQuark for the field name. This allows more efficient
690  * setting of the structure if the caller already knows the associated
691  * quark values.
692  * The last variable argument must be %NULL.
693  */
694 void
695 gst_structure_id_set (GstStructure * structure, GQuark field, ...)
696 {
697   va_list varargs;
698
699   g_return_if_fail (structure != NULL);
700
701   va_start (varargs, field);
702   gst_structure_id_set_valist_internal (structure, field, varargs);
703   va_end (varargs);
704 }
705
706 /**
707  * gst_structure_id_set_valist:
708  * @structure: a #GstStructure
709  * @fieldname: the name of the field to set
710  * @varargs: variable arguments
711  *
712  * va_list form of gst_structure_id_set().
713  */
714 void
715 gst_structure_id_set_valist (GstStructure * structure,
716     GQuark fieldname, va_list varargs)
717 {
718   g_return_if_fail (structure != NULL);
719   g_return_if_fail (IS_MUTABLE (structure));
720
721   gst_structure_id_set_valist_internal (structure, fieldname, varargs);
722 }
723
724 /**
725  * gst_structure_new_id:
726  * @name_quark: name of new structure
727  * @field_quark: the GQuark for the name of the field to set
728  * @...: variable arguments
729  *
730  * Creates a new #GstStructure with the given name as a GQuark, followed by
731  * fieldname quark, GType, argument(s) "triplets" in the same format as
732  * gst_structure_id_set(). Basically a convenience wrapper around
733  * gst_structure_new_id_empty() and gst_structure_id_set().
734  *
735  * The last variable argument must be %NULL (or 0).
736  *
737  * Free-function: gst_structure_free
738  *
739  * Returns: (transfer full): a new #GstStructure
740  */
741 GstStructure *
742 gst_structure_new_id (GQuark name_quark, GQuark field_quark, ...)
743 {
744   GstStructure *s;
745   va_list varargs;
746
747   g_return_val_if_fail (name_quark != 0, NULL);
748   g_return_val_if_fail (field_quark != 0, NULL);
749
750   s = gst_structure_new_id_empty (name_quark);
751
752   va_start (varargs, field_quark);
753   gst_structure_id_set_valist_internal (s, field_quark, varargs);
754   va_end (varargs);
755
756   return s;
757 }
758
759 #if GST_VERSION_NANO == 1
760 #define GIT_G_WARNING g_warning
761 #else
762 #define GIT_G_WARNING GST_WARNING
763 #endif
764
765 /* If the structure currently contains a field with the same name, it is
766  * replaced with the provided field. Otherwise, the field is added to the
767  * structure. The field's value is not deeply copied.
768  */
769 static void
770 gst_structure_set_field (GstStructure * structure, GstStructureField * field)
771 {
772   GstStructureField *f;
773   GType field_value_type;
774   guint i, len;
775
776   len = GST_STRUCTURE_FIELDS (structure)->len;
777
778   field_value_type = G_VALUE_TYPE (&field->value);
779   if (field_value_type == G_TYPE_STRING) {
780     const gchar *s;
781
782     s = g_value_get_string (&field->value);
783     /* only check for NULL strings in taglists, as they are allowed in message
784      * structs, e.g. error message debug strings */
785     if (G_UNLIKELY (IS_TAGLIST (structure) && (s == NULL || *s == '\0'))) {
786       if (s == NULL) {
787         GIT_G_WARNING ("Trying to set NULL string on field '%s' on taglist. "
788             "Please file a bug.", g_quark_to_string (field->name));
789         g_value_unset (&field->value);
790         return;
791       } else {
792         /* empty strings never make sense */
793         GIT_G_WARNING ("Trying to set empty string on taglist field '%s'. "
794             "Please file a bug.", g_quark_to_string (field->name));
795         g_value_unset (&field->value);
796         return;
797       }
798     } else if (G_UNLIKELY (s != NULL && !g_utf8_validate (s, -1, NULL))) {
799       g_warning ("Trying to set string on %s field '%s', but string is not "
800           "valid UTF-8. Please file a bug.",
801           IS_TAGLIST (structure) ? "taglist" : "structure",
802           g_quark_to_string (field->name));
803       g_value_unset (&field->value);
804       return;
805     }
806   } else if (G_UNLIKELY (field_value_type == G_TYPE_DATE)) {
807     const GDate *d;
808
809     d = g_value_get_boxed (&field->value);
810     /* only check for NULL GDates in taglists, as they might make sense
811      * in other, generic structs */
812     if (G_UNLIKELY ((IS_TAGLIST (structure) && d == NULL))) {
813       GIT_G_WARNING ("Trying to set NULL GDate on field '%s' on taglist. "
814           "Please file a bug.", g_quark_to_string (field->name));
815       g_value_unset (&field->value);
816       return;
817     } else if (G_UNLIKELY (d != NULL && !g_date_valid (d))) {
818       g_warning
819           ("Trying to set invalid GDate on %s field '%s'. Please file a bug.",
820           IS_TAGLIST (structure) ? "taglist" : "structure",
821           g_quark_to_string (field->name));
822       g_value_unset (&field->value);
823       return;
824     }
825   }
826
827   for (i = 0; i < len; i++) {
828     f = GST_STRUCTURE_FIELD (structure, i);
829
830     if (G_UNLIKELY (f->name == field->name)) {
831       g_value_unset (&f->value);
832       memcpy (f, field, sizeof (GstStructureField));
833       return;
834     }
835   }
836
837   g_array_append_val (GST_STRUCTURE_FIELDS (structure), *field);
838 }
839
840 /* If there is no field with the given ID, NULL is returned.
841  */
842 static GstStructureField *
843 gst_structure_id_get_field (const GstStructure * structure, GQuark field_id)
844 {
845   GstStructureField *field;
846   guint i, len;
847
848   len = GST_STRUCTURE_FIELDS (structure)->len;
849
850   for (i = 0; i < len; i++) {
851     field = GST_STRUCTURE_FIELD (structure, i);
852
853     if (G_UNLIKELY (field->name == field_id))
854       return field;
855   }
856
857   return NULL;
858 }
859
860 /* If there is no field with the given ID, NULL is returned.
861  */
862 static GstStructureField *
863 gst_structure_get_field (const GstStructure * structure,
864     const gchar * fieldname)
865 {
866   g_return_val_if_fail (structure != NULL, NULL);
867   g_return_val_if_fail (fieldname != NULL, NULL);
868
869   return gst_structure_id_get_field (structure,
870       g_quark_from_string (fieldname));
871 }
872
873 /**
874  * gst_structure_get_value:
875  * @structure: a #GstStructure
876  * @fieldname: the name of the field to get
877  *
878  * Get the value of the field with name @fieldname.
879  *
880  * Returns: the #GValue corresponding to the field with the given name.
881  */
882 const GValue *
883 gst_structure_get_value (const GstStructure * structure,
884     const gchar * fieldname)
885 {
886   GstStructureField *field;
887
888   g_return_val_if_fail (structure != NULL, NULL);
889   g_return_val_if_fail (fieldname != NULL, NULL);
890
891   field = gst_structure_get_field (structure, fieldname);
892   if (field == NULL)
893     return NULL;
894
895   return &field->value;
896 }
897
898 /**
899  * gst_structure_id_get_value:
900  * @structure: a #GstStructure
901  * @field: the #GQuark of the field to get
902  *
903  * Get the value of the field with GQuark @field.
904  *
905  * Returns: the #GValue corresponding to the field with the given name
906  *          identifier.
907  */
908 const GValue *
909 gst_structure_id_get_value (const GstStructure * structure, GQuark field)
910 {
911   GstStructureField *gsfield;
912
913   g_return_val_if_fail (structure != NULL, NULL);
914
915   gsfield = gst_structure_id_get_field (structure, field);
916   if (gsfield == NULL)
917     return NULL;
918
919   return &gsfield->value;
920 }
921
922 /**
923  * gst_structure_remove_field:
924  * @structure: a #GstStructure
925  * @fieldname: the name of the field to remove
926  *
927  * Removes the field with the given name.  If the field with the given
928  * name does not exist, the structure is unchanged.
929  */
930 void
931 gst_structure_remove_field (GstStructure * structure, const gchar * fieldname)
932 {
933   GstStructureField *field;
934   GQuark id;
935   guint i, len;
936
937   g_return_if_fail (structure != NULL);
938   g_return_if_fail (fieldname != NULL);
939   g_return_if_fail (IS_MUTABLE (structure));
940
941   id = g_quark_from_string (fieldname);
942   len = GST_STRUCTURE_FIELDS (structure)->len;
943
944   for (i = 0; i < len; i++) {
945     field = GST_STRUCTURE_FIELD (structure, i);
946
947     if (field->name == id) {
948       if (G_IS_VALUE (&field->value)) {
949         g_value_unset (&field->value);
950       }
951       GST_STRUCTURE_FIELDS (structure) =
952           g_array_remove_index (GST_STRUCTURE_FIELDS (structure), i);
953       return;
954     }
955   }
956 }
957
958 /**
959  * gst_structure_remove_fields:
960  * @structure: a #GstStructure
961  * @fieldname: the name of the field to remove
962  * @...: %NULL-terminated list of more fieldnames to remove
963  *
964  * Removes the fields with the given names. If a field does not exist, the
965  * argument is ignored.
966  */
967 void
968 gst_structure_remove_fields (GstStructure * structure,
969     const gchar * fieldname, ...)
970 {
971   va_list varargs;
972
973   g_return_if_fail (structure != NULL);
974   g_return_if_fail (fieldname != NULL);
975   /* mutability checked in remove_field */
976
977   va_start (varargs, fieldname);
978   gst_structure_remove_fields_valist (structure, fieldname, varargs);
979   va_end (varargs);
980 }
981
982 /**
983  * gst_structure_remove_fields_valist:
984  * @structure: a #GstStructure
985  * @fieldname: the name of the field to remove
986  * @varargs: %NULL-terminated list of more fieldnames to remove
987  *
988  * va_list form of gst_structure_remove_fields().
989  */
990 void
991 gst_structure_remove_fields_valist (GstStructure * structure,
992     const gchar * fieldname, va_list varargs)
993 {
994   gchar *field = (gchar *) fieldname;
995
996   g_return_if_fail (structure != NULL);
997   g_return_if_fail (fieldname != NULL);
998   /* mutability checked in remove_field */
999
1000   while (field) {
1001     gst_structure_remove_field (structure, field);
1002     field = va_arg (varargs, char *);
1003   }
1004 }
1005
1006 /**
1007  * gst_structure_remove_all_fields:
1008  * @structure: a #GstStructure
1009  *
1010  * Removes all fields in a GstStructure.
1011  */
1012 void
1013 gst_structure_remove_all_fields (GstStructure * structure)
1014 {
1015   GstStructureField *field;
1016   int i;
1017
1018   g_return_if_fail (structure != NULL);
1019   g_return_if_fail (IS_MUTABLE (structure));
1020
1021   for (i = GST_STRUCTURE_FIELDS (structure)->len - 1; i >= 0; i--) {
1022     field = GST_STRUCTURE_FIELD (structure, i);
1023
1024     if (G_IS_VALUE (&field->value)) {
1025       g_value_unset (&field->value);
1026     }
1027     GST_STRUCTURE_FIELDS (structure) =
1028         g_array_remove_index (GST_STRUCTURE_FIELDS (structure), i);
1029   }
1030 }
1031
1032 /**
1033  * gst_structure_get_field_type:
1034  * @structure: a #GstStructure
1035  * @fieldname: the name of the field
1036  *
1037  * Finds the field with the given name, and returns the type of the
1038  * value it contains.  If the field is not found, G_TYPE_INVALID is
1039  * returned.
1040  *
1041  * Returns: the #GValue of the field
1042  */
1043 GType
1044 gst_structure_get_field_type (const GstStructure * structure,
1045     const gchar * fieldname)
1046 {
1047   GstStructureField *field;
1048
1049   g_return_val_if_fail (structure != NULL, G_TYPE_INVALID);
1050   g_return_val_if_fail (fieldname != NULL, G_TYPE_INVALID);
1051
1052   field = gst_structure_get_field (structure, fieldname);
1053   if (field == NULL)
1054     return G_TYPE_INVALID;
1055
1056   return G_VALUE_TYPE (&field->value);
1057 }
1058
1059 /**
1060  * gst_structure_n_fields:
1061  * @structure: a #GstStructure
1062  *
1063  * Get the number of fields in the structure.
1064  *
1065  * Returns: the number of fields in the structure
1066  */
1067 gint
1068 gst_structure_n_fields (const GstStructure * structure)
1069 {
1070   g_return_val_if_fail (structure != NULL, 0);
1071
1072   return GST_STRUCTURE_FIELDS (structure)->len;
1073 }
1074
1075 /**
1076  * gst_structure_nth_field_name:
1077  * @structure: a #GstStructure
1078  * @index: the index to get the name of
1079  *
1080  * Get the name of the given field number, counting from 0 onwards.
1081  *
1082  * Returns: the name of the given field number
1083  */
1084 const gchar *
1085 gst_structure_nth_field_name (const GstStructure * structure, guint index)
1086 {
1087   GstStructureField *field;
1088
1089   g_return_val_if_fail (structure != NULL, NULL);
1090   g_return_val_if_fail (index < GST_STRUCTURE_FIELDS (structure)->len, NULL);
1091
1092   field = GST_STRUCTURE_FIELD (structure, index);
1093
1094   return g_quark_to_string (field->name);
1095 }
1096
1097 /**
1098  * gst_structure_foreach:
1099  * @structure: a #GstStructure
1100  * @func: (scope call): a function to call for each field
1101  * @user_data: (closure): private data
1102  *
1103  * Calls the provided function once for each field in the #GstStructure. The
1104  * function must not modify the fields. Also see gst_structure_map_in_place()
1105  * and gst_structure_filter_and_map_in_place().
1106  *
1107  * Returns: %TRUE if the supplied function returns %TRUE For each of the fields,
1108  * %FALSE otherwise.
1109  */
1110 gboolean
1111 gst_structure_foreach (const GstStructure * structure,
1112     GstStructureForeachFunc func, gpointer user_data)
1113 {
1114   guint i, len;
1115   GstStructureField *field;
1116   gboolean ret;
1117
1118   g_return_val_if_fail (structure != NULL, FALSE);
1119   g_return_val_if_fail (func != NULL, FALSE);
1120
1121   len = GST_STRUCTURE_FIELDS (structure)->len;
1122
1123   for (i = 0; i < len; i++) {
1124     field = GST_STRUCTURE_FIELD (structure, i);
1125
1126     ret = func (field->name, &field->value, user_data);
1127     if (G_UNLIKELY (!ret))
1128       return FALSE;
1129   }
1130
1131   return TRUE;
1132 }
1133
1134 /**
1135  * gst_structure_map_in_place:
1136  * @structure: a #GstStructure
1137  * @func: (scope call): a function to call for each field
1138  * @user_data: (closure): private data
1139  *
1140  * Calls the provided function once for each field in the #GstStructure. In
1141  * contrast to gst_structure_foreach(), the function may modify but not delete the
1142  * fields. The structure must be mutable.
1143  *
1144  * Returns: %TRUE if the supplied function returns %TRUE For each of the fields,
1145  * %FALSE otherwise.
1146  */
1147 gboolean
1148 gst_structure_map_in_place (GstStructure * structure,
1149     GstStructureMapFunc func, gpointer user_data)
1150 {
1151   guint i, len;
1152   GstStructureField *field;
1153   gboolean ret;
1154
1155   g_return_val_if_fail (structure != NULL, FALSE);
1156   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1157   g_return_val_if_fail (func != NULL, FALSE);
1158   len = GST_STRUCTURE_FIELDS (structure)->len;
1159
1160   for (i = 0; i < len; i++) {
1161     field = GST_STRUCTURE_FIELD (structure, i);
1162
1163     ret = func (field->name, &field->value, user_data);
1164     if (!ret)
1165       return FALSE;
1166   }
1167
1168   return TRUE;
1169 }
1170
1171 /**
1172  * gst_structure_filter_and_map_in_place:
1173  * @structure: a #GstStructure
1174  * @func: (scope call): a function to call for each field
1175  * @user_data: (closure): private data
1176  *
1177  * Calls the provided function once for each field in the #GstStructure. In
1178  * contrast to gst_structure_foreach(), the function may modify the fields.
1179  * In contrast to gst_structure_map_in_place(), the field is removed from
1180  * the structure if %FALSE is returned from the function.
1181  * The structure must be mutable.
1182  *
1183  * Since: 1.6
1184  */
1185 void
1186 gst_structure_filter_and_map_in_place (GstStructure * structure,
1187     GstStructureFilterMapFunc func, gpointer user_data)
1188 {
1189   guint i, len;
1190   GstStructureField *field;
1191   gboolean ret;
1192
1193   g_return_if_fail (structure != NULL);
1194   g_return_if_fail (IS_MUTABLE (structure));
1195   g_return_if_fail (func != NULL);
1196   len = GST_STRUCTURE_FIELDS (structure)->len;
1197
1198   for (i = 0; i < len;) {
1199     field = GST_STRUCTURE_FIELD (structure, i);
1200
1201     ret = func (field->name, &field->value, user_data);
1202
1203     if (!ret) {
1204       if (G_IS_VALUE (&field->value)) {
1205         g_value_unset (&field->value);
1206       }
1207       GST_STRUCTURE_FIELDS (structure) =
1208           g_array_remove_index (GST_STRUCTURE_FIELDS (structure), i);
1209       len = GST_STRUCTURE_FIELDS (structure)->len;
1210     } else {
1211       i++;
1212     }
1213   }
1214 }
1215
1216 /**
1217  * gst_structure_id_has_field:
1218  * @structure: a #GstStructure
1219  * @field: #GQuark of the field name
1220  *
1221  * Check if @structure contains a field named @field.
1222  *
1223  * Returns: %TRUE if the structure contains a field with the given name
1224  */
1225 gboolean
1226 gst_structure_id_has_field (const GstStructure * structure, GQuark field)
1227 {
1228   GstStructureField *f;
1229
1230   g_return_val_if_fail (structure != NULL, FALSE);
1231   g_return_val_if_fail (field != 0, FALSE);
1232
1233   f = gst_structure_id_get_field (structure, field);
1234
1235   return (f != NULL);
1236 }
1237
1238 /**
1239  * gst_structure_has_field:
1240  * @structure: a #GstStructure
1241  * @fieldname: the name of a field
1242  *
1243  * Check if @structure contains a field named @fieldname.
1244  *
1245  * Returns: %TRUE if the structure contains a field with the given name
1246  */
1247 gboolean
1248 gst_structure_has_field (const GstStructure * structure,
1249     const gchar * fieldname)
1250 {
1251   g_return_val_if_fail (structure != NULL, FALSE);
1252   g_return_val_if_fail (fieldname != NULL, FALSE);
1253
1254   return gst_structure_id_has_field (structure,
1255       g_quark_from_string (fieldname));
1256 }
1257
1258 /**
1259  * gst_structure_id_has_field_typed:
1260  * @structure: a #GstStructure
1261  * @field: #GQuark of the field name
1262  * @type: the type of a value
1263  *
1264  * Check if @structure contains a field named @field and with GType @type.
1265  *
1266  * Returns: %TRUE if the structure contains a field with the given name and type
1267  */
1268 gboolean
1269 gst_structure_id_has_field_typed (const GstStructure * structure,
1270     GQuark field, GType type)
1271 {
1272   GstStructureField *f;
1273
1274   g_return_val_if_fail (structure != NULL, FALSE);
1275   g_return_val_if_fail (field != 0, FALSE);
1276
1277   f = gst_structure_id_get_field (structure, field);
1278   if (f == NULL)
1279     return FALSE;
1280
1281   return (G_VALUE_TYPE (&f->value) == type);
1282 }
1283
1284 /**
1285  * gst_structure_has_field_typed:
1286  * @structure: a #GstStructure
1287  * @fieldname: the name of a field
1288  * @type: the type of a value
1289  *
1290  * Check if @structure contains a field named @fieldname and with GType @type.
1291  *
1292  * Returns: %TRUE if the structure contains a field with the given name and type
1293  */
1294 gboolean
1295 gst_structure_has_field_typed (const GstStructure * structure,
1296     const gchar * fieldname, GType type)
1297 {
1298   g_return_val_if_fail (structure != NULL, FALSE);
1299   g_return_val_if_fail (fieldname != NULL, FALSE);
1300
1301   return gst_structure_id_has_field_typed (structure,
1302       g_quark_from_string (fieldname), type);
1303 }
1304
1305 /* utility functions */
1306
1307 /**
1308  * gst_structure_get_boolean:
1309  * @structure: a #GstStructure
1310  * @fieldname: the name of a field
1311  * @value: (out): a pointer to a #gboolean to set
1312  *
1313  * Sets the boolean pointed to by @value corresponding to the value of the
1314  * given field.  Caller is responsible for making sure the field exists
1315  * and has the correct type.
1316  *
1317  * Returns: %TRUE if the value could be set correctly. If there was no field
1318  * with @fieldname or the existing field did not contain a boolean, this
1319  * function returns %FALSE.
1320  */
1321 gboolean
1322 gst_structure_get_boolean (const GstStructure * structure,
1323     const gchar * fieldname, gboolean * value)
1324 {
1325   GstStructureField *field;
1326
1327   g_return_val_if_fail (structure != NULL, FALSE);
1328   g_return_val_if_fail (fieldname != NULL, FALSE);
1329
1330   field = gst_structure_get_field (structure, fieldname);
1331
1332   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_BOOLEAN)
1333     return FALSE;
1334
1335   *value = gst_g_value_get_boolean_unchecked (&field->value);
1336
1337   return TRUE;
1338 }
1339
1340 /**
1341  * gst_structure_get_int:
1342  * @structure: a #GstStructure
1343  * @fieldname: the name of a field
1344  * @value: (out): a pointer to an int to set
1345  *
1346  * Sets the int pointed to by @value corresponding to the value of the
1347  * given field.  Caller is responsible for making sure the field exists
1348  * and has the correct type.
1349  *
1350  * Returns: %TRUE if the value could be set correctly. If there was no field
1351  * with @fieldname or the existing field did not contain an int, this function
1352  * returns %FALSE.
1353  */
1354 gboolean
1355 gst_structure_get_int (const GstStructure * structure,
1356     const gchar * fieldname, gint * value)
1357 {
1358   GstStructureField *field;
1359
1360   g_return_val_if_fail (structure != NULL, FALSE);
1361   g_return_val_if_fail (fieldname != NULL, FALSE);
1362   g_return_val_if_fail (value != NULL, FALSE);
1363
1364   field = gst_structure_get_field (structure, fieldname);
1365
1366   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_INT)
1367     return FALSE;
1368
1369   *value = gst_g_value_get_int_unchecked (&field->value);
1370
1371   return TRUE;
1372 }
1373
1374 /**
1375  * gst_structure_get_uint:
1376  * @structure: a #GstStructure
1377  * @fieldname: the name of a field
1378  * @value: (out): a pointer to a uint to set
1379  *
1380  * Sets the uint pointed to by @value corresponding to the value of the
1381  * given field.  Caller is responsible for making sure the field exists
1382  * and has the correct type.
1383  *
1384  * Returns: %TRUE if the value could be set correctly. If there was no field
1385  * with @fieldname or the existing field did not contain a uint, this function
1386  * returns %FALSE.
1387  */
1388 gboolean
1389 gst_structure_get_uint (const GstStructure * structure,
1390     const gchar * fieldname, guint * value)
1391 {
1392   GstStructureField *field;
1393
1394   g_return_val_if_fail (structure != NULL, FALSE);
1395   g_return_val_if_fail (fieldname != NULL, FALSE);
1396   g_return_val_if_fail (value != NULL, FALSE);
1397
1398   field = gst_structure_get_field (structure, fieldname);
1399
1400   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_UINT)
1401     return FALSE;
1402
1403   *value = gst_g_value_get_uint_unchecked (&field->value);
1404
1405   return TRUE;
1406 }
1407
1408 /**
1409  * gst_structure_get_int64:
1410  * @structure: a #GstStructure
1411  * @fieldname: the name of a field
1412  * @value: (out): a pointer to a #gint64 to set
1413  *
1414  * Sets the #gint64 pointed to by @value corresponding to the value of the
1415  * given field. Caller is responsible for making sure the field exists
1416  * and has the correct type.
1417  *
1418  * Returns: %TRUE if the value could be set correctly. If there was no field
1419  * with @fieldname or the existing field did not contain a #gint64, this function
1420  * returns %FALSE.
1421  *
1422  * Since: 1.4
1423  */
1424 gboolean
1425 gst_structure_get_int64 (const GstStructure * structure,
1426     const gchar * fieldname, gint64 * value)
1427 {
1428   GstStructureField *field;
1429
1430   g_return_val_if_fail (structure != NULL, FALSE);
1431   g_return_val_if_fail (fieldname != NULL, FALSE);
1432   g_return_val_if_fail (value != NULL, FALSE);
1433
1434   field = gst_structure_get_field (structure, fieldname);
1435
1436   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_INT64)
1437     return FALSE;
1438
1439   *value = gst_g_value_get_int64_unchecked (&field->value);
1440
1441   return TRUE;
1442 }
1443
1444 /**
1445  * gst_structure_get_uint64:
1446  * @structure: a #GstStructure
1447  * @fieldname: the name of a field
1448  * @value: (out): a pointer to a #guint64 to set
1449  *
1450  * Sets the #guint64 pointed to by @value corresponding to the value of the
1451  * given field. Caller is responsible for making sure the field exists
1452  * and has the correct type.
1453  *
1454  * Returns: %TRUE if the value could be set correctly. If there was no field
1455  * with @fieldname or the existing field did not contain a #guint64, this function
1456  * returns %FALSE.
1457  *
1458  * Since: 1.4
1459  */
1460 gboolean
1461 gst_structure_get_uint64 (const GstStructure * structure,
1462     const gchar * fieldname, guint64 * value)
1463 {
1464   GstStructureField *field;
1465
1466   g_return_val_if_fail (structure != NULL, FALSE);
1467   g_return_val_if_fail (fieldname != NULL, FALSE);
1468   g_return_val_if_fail (value != NULL, FALSE);
1469
1470   field = gst_structure_get_field (structure, fieldname);
1471
1472   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_UINT64)
1473     return FALSE;
1474
1475   *value = gst_g_value_get_uint64_unchecked (&field->value);
1476
1477   return TRUE;
1478 }
1479
1480 /**
1481  * gst_structure_get_date:
1482  * @structure: a #GstStructure
1483  * @fieldname: the name of a field
1484  * @value: (out callee-allocates): a pointer to a #GDate to set
1485  *
1486  * Sets the date pointed to by @value corresponding to the date of the
1487  * given field.  Caller is responsible for making sure the field exists
1488  * and has the correct type.
1489  *
1490  * On success @value will point to a newly-allocated copy of the date which
1491  * should be freed with g_date_free() when no longer needed (note: this is
1492  * inconsistent with e.g. gst_structure_get_string() which doesn't return a
1493  * copy of the string).
1494  *
1495  * Returns: %TRUE if the value could be set correctly. If there was no field
1496  * with @fieldname or the existing field did not contain a data, this function
1497  * returns %FALSE.
1498  */
1499 gboolean
1500 gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
1501     GDate ** value)
1502 {
1503   GstStructureField *field;
1504
1505   g_return_val_if_fail (structure != NULL, FALSE);
1506   g_return_val_if_fail (fieldname != NULL, FALSE);
1507   g_return_val_if_fail (value != NULL, FALSE);
1508
1509   field = gst_structure_get_field (structure, fieldname);
1510
1511   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_DATE)
1512     return FALSE;
1513
1514   /* FIXME: 2.0 g_value_dup_boxed() -> g_value_get_boxed() */
1515   *value = g_value_dup_boxed (&field->value);
1516
1517   return TRUE;
1518 }
1519
1520 /**
1521  * gst_structure_get_date_time:
1522  * @structure: a #GstStructure
1523  * @fieldname: the name of a field
1524  * @value: (out callee-allocates): a pointer to a #GstDateTime to set
1525  *
1526  * Sets the datetime pointed to by @value corresponding to the datetime of the
1527  * given field. Caller is responsible for making sure the field exists
1528  * and has the correct type.
1529  *
1530  * On success @value will point to a reference of the datetime which
1531  * should be unreffed with gst_date_time_unref() when no longer needed
1532  * (note: this is inconsistent with e.g. gst_structure_get_string()
1533  * which doesn't return a copy of the string).
1534  *
1535  * Returns: %TRUE if the value could be set correctly. If there was no field
1536  * with @fieldname or the existing field did not contain a data, this function
1537  * returns %FALSE.
1538  */
1539 gboolean
1540 gst_structure_get_date_time (const GstStructure * structure,
1541     const gchar * fieldname, GstDateTime ** value)
1542 {
1543   GstStructureField *field;
1544
1545   g_return_val_if_fail (structure != NULL, FALSE);
1546   g_return_val_if_fail (fieldname != NULL, FALSE);
1547   g_return_val_if_fail (value != NULL, FALSE);
1548
1549   field = gst_structure_get_field (structure, fieldname);
1550
1551   if (field == NULL)
1552     return FALSE;
1553   if (!GST_VALUE_HOLDS_DATE_TIME (&field->value))
1554     return FALSE;
1555
1556   /* FIXME 2.0: g_value_dup_boxed() -> g_value_get_boxed() */
1557   *value = g_value_dup_boxed (&field->value);
1558
1559   return TRUE;
1560 }
1561
1562 /**
1563  * gst_structure_get_clock_time:
1564  * @structure: a #GstStructure
1565  * @fieldname: the name of a field
1566  * @value: (out): a pointer to a #GstClockTime to set
1567  *
1568  * Sets the clock time pointed to by @value corresponding to the clock time
1569  * of the given field.  Caller is responsible for making sure the field exists
1570  * and has the correct type.
1571  *
1572  * Returns: %TRUE if the value could be set correctly. If there was no field
1573  * with @fieldname or the existing field did not contain a #GstClockTime, this
1574  * function returns %FALSE.
1575  */
1576 gboolean
1577 gst_structure_get_clock_time (const GstStructure * structure,
1578     const gchar * fieldname, GstClockTime * value)
1579 {
1580   return gst_structure_get_uint64 (structure, fieldname, value);
1581 }
1582
1583 /**
1584  * gst_structure_get_double:
1585  * @structure: a #GstStructure
1586  * @fieldname: the name of a field
1587  * @value: (out): a pointer to a gdouble to set
1588  *
1589  * Sets the double pointed to by @value corresponding to the value of the
1590  * given field.  Caller is responsible for making sure the field exists
1591  * and has the correct type.
1592  *
1593  * Returns: %TRUE if the value could be set correctly. If there was no field
1594  * with @fieldname or the existing field did not contain a double, this
1595  * function returns %FALSE.
1596  */
1597 gboolean
1598 gst_structure_get_double (const GstStructure * structure,
1599     const gchar * fieldname, gdouble * value)
1600 {
1601   GstStructureField *field;
1602
1603   g_return_val_if_fail (structure != NULL, FALSE);
1604   g_return_val_if_fail (fieldname != NULL, FALSE);
1605   g_return_val_if_fail (value != NULL, FALSE);
1606
1607   field = gst_structure_get_field (structure, fieldname);
1608
1609   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_DOUBLE)
1610     return FALSE;
1611
1612   *value = gst_g_value_get_double_unchecked (&field->value);
1613
1614   return TRUE;
1615 }
1616
1617 /**
1618  * gst_structure_get_string:
1619  * @structure: a #GstStructure
1620  * @fieldname: the name of a field
1621  *
1622  * Finds the field corresponding to @fieldname, and returns the string
1623  * contained in the field's value.  Caller is responsible for making
1624  * sure the field exists and has the correct type.
1625  *
1626  * The string should not be modified, and remains valid until the next
1627  * call to a gst_structure_*() function with the given structure.
1628  *
1629  * Returns: (nullable): a pointer to the string or %NULL when the
1630  * field did not exist or did not contain a string.
1631  */
1632 const gchar *
1633 gst_structure_get_string (const GstStructure * structure,
1634     const gchar * fieldname)
1635 {
1636   GstStructureField *field;
1637
1638   g_return_val_if_fail (structure != NULL, NULL);
1639   g_return_val_if_fail (fieldname != NULL, NULL);
1640
1641   field = gst_structure_get_field (structure, fieldname);
1642
1643   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_STRING)
1644     return NULL;
1645
1646   return gst_g_value_get_string_unchecked (&field->value);
1647 }
1648
1649 /**
1650  * gst_structure_get_enum:
1651  * @structure: a #GstStructure
1652  * @fieldname: the name of a field
1653  * @enumtype: the enum type of a field
1654  * @value: (out): a pointer to an int to set
1655  *
1656  * Sets the int pointed to by @value corresponding to the value of the
1657  * given field.  Caller is responsible for making sure the field exists,
1658  * has the correct type and that the enumtype is correct.
1659  *
1660  * Returns: %TRUE if the value could be set correctly. If there was no field
1661  * with @fieldname or the existing field did not contain an enum of the given
1662  * type, this function returns %FALSE.
1663  */
1664 gboolean
1665 gst_structure_get_enum (const GstStructure * structure,
1666     const gchar * fieldname, GType enumtype, gint * value)
1667 {
1668   GstStructureField *field;
1669
1670   g_return_val_if_fail (structure != NULL, FALSE);
1671   g_return_val_if_fail (fieldname != NULL, FALSE);
1672   g_return_val_if_fail (enumtype != G_TYPE_INVALID, FALSE);
1673   g_return_val_if_fail (value != NULL, FALSE);
1674
1675   field = gst_structure_get_field (structure, fieldname);
1676
1677   if (field == NULL)
1678     return FALSE;
1679   if (!G_TYPE_CHECK_VALUE_TYPE (&field->value, enumtype))
1680     return FALSE;
1681
1682   *value = g_value_get_enum (&field->value);
1683
1684   return TRUE;
1685 }
1686
1687 /**
1688  * gst_structure_get_fraction:
1689  * @structure: a #GstStructure
1690  * @fieldname: the name of a field
1691  * @value_numerator: (out): a pointer to an int to set
1692  * @value_denominator: (out): a pointer to an int to set
1693  *
1694  * Sets the integers pointed to by @value_numerator and @value_denominator
1695  * corresponding to the value of the given field.  Caller is responsible
1696  * for making sure the field exists and has the correct type.
1697  *
1698  * Returns: %TRUE if the values could be set correctly. If there was no field
1699  * with @fieldname or the existing field did not contain a GstFraction, this
1700  * function returns %FALSE.
1701  */
1702 gboolean
1703 gst_structure_get_fraction (const GstStructure * structure,
1704     const gchar * fieldname, gint * value_numerator, gint * value_denominator)
1705 {
1706   GstStructureField *field;
1707
1708   g_return_val_if_fail (structure != NULL, FALSE);
1709   g_return_val_if_fail (fieldname != NULL, FALSE);
1710   g_return_val_if_fail (value_numerator != NULL, FALSE);
1711   g_return_val_if_fail (value_denominator != NULL, FALSE);
1712
1713   field = gst_structure_get_field (structure, fieldname);
1714
1715   if (field == NULL || G_VALUE_TYPE (&field->value) != GST_TYPE_FRACTION)
1716     return FALSE;
1717
1718   *value_numerator = gst_value_get_fraction_numerator (&field->value);
1719   *value_denominator = gst_value_get_fraction_denominator (&field->value);
1720
1721   return TRUE;
1722 }
1723
1724 /**
1725  * gst_structure_get_flagset:
1726  * @structure: a #GstStructure
1727  * @fieldname: the name of a field
1728  * @value_flags: (out) (allow-none): a pointer to a guint for the flags field
1729  * @value_mask: (out) (allow-none): a pointer to a guint for the mask field
1730  *
1731  * Read the GstFlagSet flags and mask out of the structure into the
1732  * provided pointers.
1733  *
1734  * Returns: %TRUE if the values could be set correctly. If there was no field
1735  * with @fieldname or the existing field did not contain a GstFlagSet, this
1736  * function returns %FALSE.
1737  *
1738  * Since: 1.6
1739  */
1740 gboolean
1741 gst_structure_get_flagset (const GstStructure * structure,
1742     const gchar * fieldname, guint * value_flags, guint * value_mask)
1743 {
1744   GstStructureField *field;
1745
1746   g_return_val_if_fail (structure != NULL, FALSE);
1747   g_return_val_if_fail (fieldname != NULL, FALSE);
1748
1749   field = gst_structure_get_field (structure, fieldname);
1750
1751   if (field == NULL || !GST_VALUE_HOLDS_FLAG_SET (&field->value))
1752     return FALSE;
1753
1754   if (value_flags)
1755     *value_flags = gst_value_get_flagset_flags (&field->value);
1756   if (value_mask)
1757     *value_mask = gst_value_get_flagset_mask (&field->value);
1758
1759   return TRUE;
1760 }
1761
1762 typedef struct _GstStructureAbbreviation
1763 {
1764   const gchar *type_name;
1765   GType type;
1766 }
1767 GstStructureAbbreviation;
1768
1769 /* return a copy of an array of GstStructureAbbreviation containing all the
1770  * known type_string, GType maps, including abbreviations for common types */
1771 static GstStructureAbbreviation *
1772 gst_structure_get_abbrs (gint * n_abbrs)
1773 {
1774   static GstStructureAbbreviation *abbrs = NULL;
1775   static volatile gsize num = 0;
1776
1777   if (g_once_init_enter (&num)) {
1778     /* dynamically generate the array */
1779     gsize _num;
1780     GstStructureAbbreviation dyn_abbrs[] = {
1781       {"int", G_TYPE_INT}
1782       ,
1783       {"i", G_TYPE_INT}
1784       ,
1785       {"uint", G_TYPE_UINT}
1786       ,
1787       {"u", G_TYPE_UINT}
1788       ,
1789       {"float", G_TYPE_FLOAT}
1790       ,
1791       {"f", G_TYPE_FLOAT}
1792       ,
1793       {"double", G_TYPE_DOUBLE}
1794       ,
1795       {"d", G_TYPE_DOUBLE}
1796       ,
1797       {"buffer", GST_TYPE_BUFFER}
1798       ,
1799       {"fraction", GST_TYPE_FRACTION}
1800       ,
1801       {"boolean", G_TYPE_BOOLEAN}
1802       ,
1803       {"bool", G_TYPE_BOOLEAN}
1804       ,
1805       {"b", G_TYPE_BOOLEAN}
1806       ,
1807       {"string", G_TYPE_STRING}
1808       ,
1809       {"str", G_TYPE_STRING}
1810       ,
1811       {"s", G_TYPE_STRING}
1812       ,
1813       {"structure", GST_TYPE_STRUCTURE}
1814       ,
1815       {"date", G_TYPE_DATE}
1816       ,
1817       {"datetime", GST_TYPE_DATE_TIME}
1818       ,
1819       {"bitmask", GST_TYPE_BITMASK}
1820       ,
1821       {"sample", GST_TYPE_SAMPLE}
1822       ,
1823       {"taglist", GST_TYPE_TAG_LIST}
1824     };
1825     _num = G_N_ELEMENTS (dyn_abbrs);
1826     /* permanently allocate and copy the array now */
1827     abbrs = g_new0 (GstStructureAbbreviation, _num);
1828     memcpy (abbrs, dyn_abbrs, sizeof (GstStructureAbbreviation) * _num);
1829     g_once_init_leave (&num, _num);
1830   }
1831   *n_abbrs = num;
1832
1833   return abbrs;
1834 }
1835
1836 /* given a type_name that could be a type abbreviation or a registered GType,
1837  * return a matching GType */
1838 static GType
1839 gst_structure_gtype_from_abbr (const char *type_name)
1840 {
1841   int i;
1842   GstStructureAbbreviation *abbrs;
1843   gint n_abbrs;
1844
1845   g_return_val_if_fail (type_name != NULL, G_TYPE_INVALID);
1846
1847   abbrs = gst_structure_get_abbrs (&n_abbrs);
1848
1849   for (i = 0; i < n_abbrs; i++) {
1850     if (strcmp (type_name, abbrs[i].type_name) == 0) {
1851       return abbrs[i].type;
1852     }
1853   }
1854
1855   /* this is the fallback */
1856   return g_type_from_name (type_name);
1857 }
1858
1859 static const char *
1860 gst_structure_to_abbr (GType type)
1861 {
1862   int i;
1863   GstStructureAbbreviation *abbrs;
1864   gint n_abbrs;
1865
1866   g_return_val_if_fail (type != G_TYPE_INVALID, NULL);
1867
1868   abbrs = gst_structure_get_abbrs (&n_abbrs);
1869
1870   for (i = 0; i < n_abbrs; i++) {
1871     if (type == abbrs[i].type) {
1872       return abbrs[i].type_name;
1873     }
1874   }
1875
1876   return g_type_name (type);
1877 }
1878
1879 static GType
1880 gst_structure_value_get_generic_type (const GValue * val)
1881 {
1882   if (G_VALUE_TYPE (val) == GST_TYPE_LIST
1883       || G_VALUE_TYPE (val) == GST_TYPE_ARRAY) {
1884     GArray *array = g_value_peek_pointer (val);
1885
1886     if (array->len > 0) {
1887       GValue *value = &g_array_index (array, GValue, 0);
1888
1889       return gst_structure_value_get_generic_type (value);
1890     } else {
1891       return G_TYPE_INT;
1892     }
1893   } else if (G_VALUE_TYPE (val) == GST_TYPE_INT_RANGE) {
1894     return G_TYPE_INT;
1895   } else if (G_VALUE_TYPE (val) == GST_TYPE_INT64_RANGE) {
1896     return G_TYPE_INT64;
1897   } else if (G_VALUE_TYPE (val) == GST_TYPE_DOUBLE_RANGE) {
1898     return G_TYPE_DOUBLE;
1899   } else if (G_VALUE_TYPE (val) == GST_TYPE_FRACTION_RANGE) {
1900     return GST_TYPE_FRACTION;
1901   }
1902   return G_VALUE_TYPE (val);
1903 }
1904
1905 gboolean
1906 priv_gst_structure_append_to_gstring (const GstStructure * structure,
1907     GString * s)
1908 {
1909   GstStructureField *field;
1910   guint i, len;
1911
1912   g_return_val_if_fail (s != NULL, FALSE);
1913
1914   len = GST_STRUCTURE_FIELDS (structure)->len;
1915   for (i = 0; i < len; i++) {
1916     char *t;
1917     GType type;
1918
1919     field = GST_STRUCTURE_FIELD (structure, i);
1920
1921     t = gst_value_serialize (&field->value);
1922     type = gst_structure_value_get_generic_type (&field->value);
1923
1924     g_string_append_len (s, ", ", 2);
1925     /* FIXME: do we need to escape fieldnames? */
1926     g_string_append (s, g_quark_to_string (field->name));
1927     g_string_append_len (s, "=(", 2);
1928     g_string_append (s, gst_structure_to_abbr (type));
1929     g_string_append_c (s, ')');
1930     if (t) {
1931       g_string_append (s, t);
1932       g_free (t);
1933     } else {
1934       GST_WARNING ("No value transform to serialize field '%s' of type '%s'",
1935           g_quark_to_string (field->name), gst_structure_to_abbr (type));
1936       g_string_append (s, "NULL");
1937     }
1938   }
1939
1940   g_string_append_c (s, ';');
1941   return TRUE;
1942 }
1943
1944 gboolean
1945 priv__gst_structure_append_template_to_gstring (GQuark field_id,
1946     const GValue * value, gpointer user_data)
1947 {
1948   GType type = gst_structure_value_get_generic_type (value);
1949   GString *s = (GString *) user_data;
1950
1951   g_string_append_len (s, ", ", 2);
1952   /* FIXME: do we need to escape fieldnames? */
1953   g_string_append (s, g_quark_to_string (field_id));
1954   g_string_append_len (s, "=(", 2);
1955   g_string_append (s, gst_structure_to_abbr (type));
1956   g_string_append_c (s, ')');
1957
1958   //TODO(ensonic): table like GstStructureAbbreviation (or extend it)
1959   if (type == G_TYPE_INT) {
1960     g_string_append_len (s, "%i", 2);
1961   } else if (type == G_TYPE_UINT) {
1962     g_string_append_len (s, "%u", 2);
1963   } else if (type == G_TYPE_FLOAT) {
1964     g_string_append_len (s, "%f", 2);
1965   } else if (type == G_TYPE_DOUBLE) {
1966     g_string_append_len (s, "%lf", 3);
1967   } else if (type == G_TYPE_STRING) {
1968     g_string_append_len (s, "%s", 2);
1969   } else if (type == G_TYPE_BOOLEAN) {
1970     /* we normally store this as a string, but can parse it also from an int */
1971     g_string_append_len (s, "%i", 2);
1972   } else if (type == G_TYPE_INT64) {
1973     g_string_append (s, "%" G_GINT64_FORMAT);
1974   } else if (type == G_TYPE_UINT64) {
1975     g_string_append (s, "%" G_GUINT64_FORMAT);
1976   } else if (type == GST_TYPE_STRUCTURE) {
1977     g_string_append (s, "%" GST_WRAPPED_PTR_FORMAT);
1978   } else if (g_type_is_a (type, G_TYPE_ENUM)
1979       || g_type_is_a (type, G_TYPE_FLAGS)) {
1980     g_string_append (s, "%i");
1981   } else if (type == G_TYPE_POINTER) {
1982     g_string_append_len (s, "%p", 2);
1983   } else {
1984     GST_WARNING ("unhandled type: %s", g_type_name (type));
1985     g_string_append (s, "%" GST_WRAPPED_PTR_FORMAT);
1986   }
1987
1988   return TRUE;
1989 }
1990
1991 /**
1992  * gst_structure_to_string:
1993  * @structure: a #GstStructure
1994  *
1995  * Converts @structure to a human-readable string representation.
1996  *
1997  * For debugging purposes its easier to do something like this:
1998  * |[<!-- language="C" -->
1999  * GST_LOG ("structure is %" GST_PTR_FORMAT, structure);
2000  * ]|
2001  * This prints the structure in human readable form.
2002  *
2003  * The current implementation of serialization will lead to unexpected results
2004  * when there are nested #GstCaps / #GstStructure deeper than one level.
2005  *
2006  * Free-function: g_free
2007  *
2008  * Returns: (transfer full): a pointer to string allocated by g_malloc().
2009  *     g_free() after usage.
2010  */
2011 gchar *
2012 gst_structure_to_string (const GstStructure * structure)
2013 {
2014   GString *s;
2015
2016   /* NOTE:  This function is potentially called by the debug system,
2017    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2018    * should be careful to avoid recursion.  This includes any functions
2019    * called by gst_structure_to_string.  In particular, calls should
2020    * not use the GST_PTR_FORMAT extension.  */
2021
2022   g_return_val_if_fail (structure != NULL, NULL);
2023
2024   /* we estimate a minimum size based on the number of fields in order to
2025    * avoid unnecessary reallocs within GString */
2026   s = g_string_sized_new (STRUCTURE_ESTIMATED_STRING_LEN (structure));
2027   g_string_append (s, g_quark_to_string (structure->name));
2028   priv_gst_structure_append_to_gstring (structure, s);
2029   return g_string_free (s, FALSE);
2030 }
2031
2032 /*
2033  * r will still point to the string. if end == next, the string will not be
2034  * null-terminated. In all other cases it will be.
2035  * end = pointer to char behind end of string, next = pointer to start of
2036  * unread data.
2037  * THIS FUNCTION MODIFIES THE STRING AND DETECTS INSIDE A NONTERMINATED STRING
2038  */
2039 static gboolean
2040 gst_structure_parse_string (gchar * s, gchar ** end, gchar ** next,
2041     gboolean unescape)
2042 {
2043   gchar *w;
2044
2045   if (*s == 0)
2046     return FALSE;
2047
2048   if (*s != '"') {
2049     int ret;
2050
2051     ret = gst_structure_parse_simple_string (s, end);
2052     *next = *end;
2053
2054     return ret;
2055   }
2056
2057   if (unescape) {
2058     w = s;
2059     s++;
2060     while (*s != '"') {
2061       if (G_UNLIKELY (*s == 0))
2062         return FALSE;
2063       if (G_UNLIKELY (*s == '\\')) {
2064         s++;
2065         if (G_UNLIKELY (*s == 0))
2066           return FALSE;
2067       }
2068       *w = *s;
2069       w++;
2070       s++;
2071     }
2072     s++;
2073   } else {
2074     /* Find the closing quotes */
2075     s++;
2076     while (*s != '"') {
2077       if (G_UNLIKELY (*s == 0))
2078         return FALSE;
2079       if (G_UNLIKELY (*s == '\\')) {
2080         s++;
2081         if (G_UNLIKELY (*s == 0))
2082           return FALSE;
2083       }
2084       s++;
2085     }
2086     s++;
2087     w = s;
2088   }
2089
2090   *end = w;
2091   *next = s;
2092
2093   return TRUE;
2094 }
2095
2096 static gboolean
2097 gst_structure_parse_range (gchar * s, gchar ** after, GValue * value,
2098     GType type)
2099 {
2100   GValue value1 = { 0 };
2101   GValue value2 = { 0 };
2102   GValue value3 = { 0 };
2103   GType range_type;
2104   gboolean ret, have_step = FALSE;
2105
2106   if (*s != '[')
2107     return FALSE;
2108   s++;
2109
2110   ret = gst_structure_parse_value (s, &s, &value1, type);
2111   if (!ret)
2112     return FALSE;
2113
2114   while (g_ascii_isspace (*s))
2115     s++;
2116
2117   if (*s != ',')
2118     return FALSE;
2119   s++;
2120
2121   while (g_ascii_isspace (*s))
2122     s++;
2123
2124   ret = gst_structure_parse_value (s, &s, &value2, type);
2125   if (!ret)
2126     return FALSE;
2127
2128   while (g_ascii_isspace (*s))
2129     s++;
2130
2131   /* optional step for int and int64 */
2132   if (G_VALUE_TYPE (&value1) == G_TYPE_INT
2133       || G_VALUE_TYPE (&value1) == G_TYPE_INT64) {
2134     if (*s == ',') {
2135       s++;
2136
2137       while (g_ascii_isspace (*s))
2138         s++;
2139
2140       ret = gst_structure_parse_value (s, &s, &value3, type);
2141       if (!ret)
2142         return FALSE;
2143
2144       while (g_ascii_isspace (*s))
2145         s++;
2146
2147       have_step = TRUE;
2148     }
2149   }
2150
2151   if (*s != ']')
2152     return FALSE;
2153   s++;
2154
2155   if (G_VALUE_TYPE (&value1) != G_VALUE_TYPE (&value2))
2156     return FALSE;
2157   if (have_step && G_VALUE_TYPE (&value1) != G_VALUE_TYPE (&value3))
2158     return FALSE;
2159
2160   if (G_VALUE_TYPE (&value1) == G_TYPE_DOUBLE) {
2161     range_type = GST_TYPE_DOUBLE_RANGE;
2162     g_value_init (value, range_type);
2163     gst_value_set_double_range (value,
2164         gst_g_value_get_double_unchecked (&value1),
2165         gst_g_value_get_double_unchecked (&value2));
2166   } else if (G_VALUE_TYPE (&value1) == G_TYPE_INT) {
2167     range_type = GST_TYPE_INT_RANGE;
2168     g_value_init (value, range_type);
2169     if (have_step)
2170       gst_value_set_int_range_step (value,
2171           gst_g_value_get_int_unchecked (&value1),
2172           gst_g_value_get_int_unchecked (&value2),
2173           gst_g_value_get_int_unchecked (&value3));
2174     else
2175       gst_value_set_int_range (value, gst_g_value_get_int_unchecked (&value1),
2176           gst_g_value_get_int_unchecked (&value2));
2177   } else if (G_VALUE_TYPE (&value1) == G_TYPE_INT64) {
2178     range_type = GST_TYPE_INT64_RANGE;
2179     g_value_init (value, range_type);
2180     if (have_step)
2181       gst_value_set_int64_range_step (value,
2182           gst_g_value_get_int64_unchecked (&value1),
2183           gst_g_value_get_int64_unchecked (&value2),
2184           gst_g_value_get_int64_unchecked (&value3));
2185     else
2186       gst_value_set_int64_range (value,
2187           gst_g_value_get_int64_unchecked (&value1),
2188           gst_g_value_get_int64_unchecked (&value2));
2189   } else if (G_VALUE_TYPE (&value1) == GST_TYPE_FRACTION) {
2190     range_type = GST_TYPE_FRACTION_RANGE;
2191     g_value_init (value, range_type);
2192     gst_value_set_fraction_range (value, &value1, &value2);
2193   } else {
2194     return FALSE;
2195   }
2196
2197   *after = s;
2198   return TRUE;
2199 }
2200
2201 static gboolean
2202 gst_structure_parse_any_list (gchar * s, gchar ** after, GValue * value,
2203     GType type, GType list_type, char begin, char end)
2204 {
2205   GValue list_value = { 0 };
2206   gboolean ret;
2207   GArray *array;
2208
2209   g_value_init (value, list_type);
2210   array = g_value_peek_pointer (value);
2211
2212   if (*s != begin)
2213     return FALSE;
2214   s++;
2215
2216   while (g_ascii_isspace (*s))
2217     s++;
2218   if (*s == end) {
2219     s++;
2220     *after = s;
2221     return TRUE;
2222   }
2223
2224   ret = gst_structure_parse_value (s, &s, &list_value, type);
2225   if (!ret)
2226     return FALSE;
2227
2228   g_array_append_val (array, list_value);
2229
2230   while (g_ascii_isspace (*s))
2231     s++;
2232
2233   while (*s != end) {
2234     if (*s != ',')
2235       return FALSE;
2236     s++;
2237
2238     while (g_ascii_isspace (*s))
2239       s++;
2240
2241     memset (&list_value, 0, sizeof (list_value));
2242     ret = gst_structure_parse_value (s, &s, &list_value, type);
2243     if (!ret)
2244       return FALSE;
2245
2246     g_array_append_val (array, list_value);
2247     while (g_ascii_isspace (*s))
2248       s++;
2249   }
2250
2251   s++;
2252
2253   *after = s;
2254   return TRUE;
2255 }
2256
2257 static gboolean
2258 gst_structure_parse_list (gchar * s, gchar ** after, GValue * value, GType type)
2259 {
2260   return gst_structure_parse_any_list (s, after, value, type, GST_TYPE_LIST,
2261       '{', '}');
2262 }
2263
2264 static gboolean
2265 gst_structure_parse_array (gchar * s, gchar ** after, GValue * value,
2266     GType type)
2267 {
2268   return gst_structure_parse_any_list (s, after, value, type,
2269       GST_TYPE_ARRAY, '<', '>');
2270 }
2271
2272 static gboolean
2273 gst_structure_parse_simple_string (gchar * str, gchar ** end)
2274 {
2275   char *s = str;
2276
2277   while (G_LIKELY (GST_ASCII_IS_STRING (*s))) {
2278     s++;
2279   }
2280
2281   *end = s;
2282
2283   return (s != str);
2284 }
2285
2286 static gboolean
2287 gst_structure_parse_field (gchar * str,
2288     gchar ** after, GstStructureField * field)
2289 {
2290   gchar *name;
2291   gchar *name_end;
2292   gchar *s;
2293   gchar c;
2294
2295   s = str;
2296
2297   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
2298     s++;
2299   name = s;
2300   if (G_UNLIKELY (!gst_structure_parse_simple_string (s, &name_end))) {
2301     GST_WARNING ("failed to parse simple string, str=%s", str);
2302     return FALSE;
2303   }
2304
2305   s = name_end;
2306   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
2307     s++;
2308
2309   if (G_UNLIKELY (*s != '=')) {
2310     GST_WARNING ("missing assignment operator in the field, str=%s", str);
2311     return FALSE;
2312   }
2313   s++;
2314
2315   c = *name_end;
2316   *name_end = '\0';
2317   field->name = g_quark_from_string (name);
2318   GST_DEBUG ("trying field name '%s'", name);
2319   *name_end = c;
2320
2321   if (G_UNLIKELY (!gst_structure_parse_value (s, &s, &field->value,
2322               G_TYPE_INVALID))) {
2323     GST_WARNING ("failed to parse value %s", str);
2324     return FALSE;
2325   }
2326
2327   *after = s;
2328   return TRUE;
2329 }
2330
2331 static gboolean
2332 gst_structure_parse_value (gchar * str,
2333     gchar ** after, GValue * value, GType default_type)
2334 {
2335   gchar *type_name;
2336   gchar *type_end;
2337   gchar *value_s;
2338   gchar *value_end;
2339   gchar *s;
2340   gchar c;
2341   int ret = 0;
2342   GType type = default_type;
2343
2344   s = str;
2345   while (g_ascii_isspace (*s))
2346     s++;
2347
2348   /* check if there's a (type_name) 'cast' */
2349   type_name = NULL;
2350   if (*s == '(') {
2351     s++;
2352     while (g_ascii_isspace (*s))
2353       s++;
2354     type_name = s;
2355     if (G_UNLIKELY (!gst_structure_parse_simple_string (s, &type_end)))
2356       return FALSE;
2357     s = type_end;
2358     while (g_ascii_isspace (*s))
2359       s++;
2360     if (G_UNLIKELY (*s != ')'))
2361       return FALSE;
2362     s++;
2363     while (g_ascii_isspace (*s))
2364       s++;
2365
2366     c = *type_end;
2367     *type_end = 0;
2368     type = gst_structure_gtype_from_abbr (type_name);
2369     GST_DEBUG ("trying type name '%s'", type_name);
2370     *type_end = c;
2371
2372     if (G_UNLIKELY (type == G_TYPE_INVALID)) {
2373       GST_WARNING ("invalid type");
2374       return FALSE;
2375     }
2376   }
2377
2378   while (g_ascii_isspace (*s))
2379     s++;
2380   if (*s == '[') {
2381     ret = gst_structure_parse_range (s, &s, value, type);
2382   } else if (*s == '{') {
2383     ret = gst_structure_parse_list (s, &s, value, type);
2384   } else if (*s == '<') {
2385     ret = gst_structure_parse_array (s, &s, value, type);
2386   } else {
2387     value_s = s;
2388
2389     if (G_UNLIKELY (type == G_TYPE_INVALID)) {
2390       GType try_types[] =
2391           { G_TYPE_INT, G_TYPE_DOUBLE, GST_TYPE_FRACTION, GST_TYPE_FLAG_SET,
2392         G_TYPE_BOOLEAN, G_TYPE_STRING
2393       };
2394       int i;
2395
2396       if (G_UNLIKELY (!gst_structure_parse_string (s, &value_end, &s, TRUE)))
2397         return FALSE;
2398       /* Set NULL terminator for deserialization */
2399       c = *value_end;
2400       *value_end = '\0';
2401
2402       for (i = 0; i < G_N_ELEMENTS (try_types); i++) {
2403         g_value_init (value, try_types[i]);
2404         ret = gst_value_deserialize (value, value_s);
2405         if (ret)
2406           break;
2407         g_value_unset (value);
2408       }
2409     } else {
2410       g_value_init (value, type);
2411
2412       if (G_UNLIKELY (!gst_structure_parse_string (s, &value_end, &s,
2413                   (type != G_TYPE_STRING))))
2414         return FALSE;
2415       /* Set NULL terminator for deserialization */
2416       c = *value_end;
2417       *value_end = '\0';
2418
2419       ret = gst_value_deserialize (value, value_s);
2420       if (G_UNLIKELY (!ret))
2421         g_value_unset (value);
2422     }
2423     *value_end = c;
2424   }
2425
2426   *after = s;
2427
2428   return ret;
2429 }
2430
2431 gboolean
2432 priv_gst_structure_parse_name (gchar * str, gchar ** start, gchar ** end,
2433     gchar ** next)
2434 {
2435   char *w;
2436   char *r;
2437
2438   r = str;
2439
2440   /* skip spaces (FIXME: _isspace treats tabs and newlines as space!) */
2441   while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
2442               && g_ascii_isspace (r[1]))))
2443     r++;
2444
2445   *start = r;
2446
2447   if (G_UNLIKELY (!gst_structure_parse_string (r, &w, &r, TRUE))) {
2448     GST_WARNING ("Failed to parse structure string '%s'", str);
2449     return FALSE;
2450   }
2451
2452   *end = w;
2453   *next = r;
2454
2455   return TRUE;
2456 }
2457
2458 gboolean
2459 priv_gst_structure_parse_fields (gchar * str, gchar ** end,
2460     GstStructure * structure)
2461 {
2462   gchar *r;
2463   GstStructureField field;
2464
2465   r = str;
2466
2467   do {
2468     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
2469                 && g_ascii_isspace (r[1]))))
2470       r++;
2471     if (*r == ';') {
2472       /* end of structure, get the next char and finish */
2473       r++;
2474       break;
2475     }
2476     if (*r == '\0') {
2477       /* accept \0 as end delimiter */
2478       break;
2479     }
2480     if (G_UNLIKELY (*r != ',')) {
2481       GST_WARNING ("Failed to find delimiter, r=%s", r);
2482       return FALSE;
2483     }
2484     r++;
2485     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
2486                 && g_ascii_isspace (r[1]))))
2487       r++;
2488
2489     memset (&field, 0, sizeof (field));
2490     if (G_UNLIKELY (!gst_structure_parse_field (r, &r, &field))) {
2491       GST_WARNING ("Failed to parse field, r=%s", r);
2492       return FALSE;
2493     }
2494     gst_structure_set_field (structure, &field);
2495   } while (TRUE);
2496
2497   *end = r;
2498
2499   return TRUE;
2500 }
2501
2502 /**
2503  * gst_structure_new_from_string:
2504  * @string: a string representation of a #GstStructure
2505  *
2506  * Creates a #GstStructure from a string representation.
2507  * If end is not %NULL, a pointer to the place inside the given string
2508  * where parsing ended will be returned.
2509  *
2510  * The current implementation of serialization will lead to unexpected results
2511  * when there are nested #GstCaps / #GstStructure deeper than one level.
2512  *
2513  * Free-function: gst_structure_free
2514  *
2515  * Returns: (transfer full) (nullable): a new #GstStructure or %NULL
2516  *     when the string could not be parsed. Free with
2517  *     gst_structure_free() after use.
2518  *
2519  * Since: 1.2
2520  */
2521 GstStructure *
2522 gst_structure_new_from_string (const gchar * string)
2523 {
2524   return gst_structure_from_string (string, NULL);
2525 }
2526
2527 /**
2528  * gst_structure_from_string:
2529  * @string: a string representation of a #GstStructure.
2530  * @end: (out) (allow-none) (transfer none) (skip): pointer to store the end of the string in.
2531  *
2532  * Creates a #GstStructure from a string representation.
2533  * If end is not %NULL, a pointer to the place inside the given string
2534  * where parsing ended will be returned.
2535  *
2536  * Free-function: gst_structure_free
2537  *
2538  * Returns: (transfer full) (nullable): a new #GstStructure or %NULL
2539  *     when the string could not be parsed. Free with
2540  *     gst_structure_free() after use.
2541  */
2542 GstStructure *
2543 gst_structure_from_string (const gchar * string, gchar ** end)
2544 {
2545   char *name;
2546   char *copy;
2547   char *w;
2548   char *r;
2549   char save;
2550   GstStructure *structure = NULL;
2551
2552   g_return_val_if_fail (string != NULL, NULL);
2553
2554   copy = g_strdup (string);
2555   r = copy;
2556
2557   if (!priv_gst_structure_parse_name (r, &name, &w, &r))
2558     goto error;
2559
2560   save = *w;
2561   *w = '\0';
2562   structure = gst_structure_new_empty (name);
2563   *w = save;
2564
2565   if (G_UNLIKELY (structure == NULL))
2566     goto error;
2567
2568   if (!priv_gst_structure_parse_fields (r, &r, structure))
2569     goto error;
2570
2571   if (end)
2572     *end = (char *) string + (r - copy);
2573   else if (*r)
2574     g_warning ("gst_structure_from_string did not consume whole string,"
2575         " but caller did not provide end pointer (\"%s\")", string);
2576
2577   g_free (copy);
2578   return structure;
2579
2580 error:
2581   if (structure)
2582     gst_structure_free (structure);
2583   g_free (copy);
2584   return NULL;
2585 }
2586
2587 static void
2588 gst_structure_transform_to_string (const GValue * src_value,
2589     GValue * dest_value)
2590 {
2591   g_return_if_fail (src_value != NULL);
2592   g_return_if_fail (dest_value != NULL);
2593
2594   dest_value->data[0].v_pointer =
2595       gst_structure_to_string (src_value->data[0].v_pointer);
2596 }
2597
2598 static GstStructure *
2599 gst_structure_copy_conditional (const GstStructure * structure)
2600 {
2601   if (structure)
2602     return gst_structure_copy (structure);
2603   return NULL;
2604 }
2605
2606 /* fixate utility functions */
2607
2608 /**
2609  * gst_structure_fixate_field_nearest_int:
2610  * @structure: a #GstStructure
2611  * @field_name: a field in @structure
2612  * @target: the target value of the fixation
2613  *
2614  * Fixates a #GstStructure by changing the given field to the nearest
2615  * integer to @target that is a subset of the existing field.
2616  *
2617  * Returns: %TRUE if the structure could be fixated
2618  */
2619 gboolean
2620 gst_structure_fixate_field_nearest_int (GstStructure * structure,
2621     const char *field_name, int target)
2622 {
2623   const GValue *value;
2624
2625   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2626   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2627
2628   value = gst_structure_get_value (structure, field_name);
2629
2630   if (G_VALUE_TYPE (value) == G_TYPE_INT) {
2631     /* already fixed */
2632     return FALSE;
2633   } else if (G_VALUE_TYPE (value) == GST_TYPE_INT_RANGE) {
2634     int x;
2635
2636     x = gst_value_get_int_range_min (value);
2637     if (target < x)
2638       target = x;
2639     x = gst_value_get_int_range_max (value);
2640     if (target > x)
2641       target = x;
2642     gst_structure_set (structure, field_name, G_TYPE_INT, target, NULL);
2643     return TRUE;
2644   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2645     const GValue *list_value;
2646     int i, n;
2647     int best = 0;
2648     int best_index = -1;
2649
2650     n = gst_value_list_get_size (value);
2651     for (i = 0; i < n; i++) {
2652       list_value = gst_value_list_get_value (value, i);
2653       if (G_VALUE_TYPE (list_value) == G_TYPE_INT) {
2654         int x = gst_g_value_get_int_unchecked (list_value);
2655
2656         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
2657           best_index = i;
2658           best = x;
2659         }
2660       }
2661     }
2662     if (best_index != -1) {
2663       gst_structure_set (structure, field_name, G_TYPE_INT, best, NULL);
2664       return TRUE;
2665     }
2666     return FALSE;
2667   }
2668
2669   return FALSE;
2670 }
2671
2672 /**
2673  * gst_structure_fixate_field_nearest_double:
2674  * @structure: a #GstStructure
2675  * @field_name: a field in @structure
2676  * @target: the target value of the fixation
2677  *
2678  * Fixates a #GstStructure by changing the given field to the nearest
2679  * double to @target that is a subset of the existing field.
2680  *
2681  * Returns: %TRUE if the structure could be fixated
2682  */
2683 gboolean
2684 gst_structure_fixate_field_nearest_double (GstStructure * structure,
2685     const char *field_name, double target)
2686 {
2687   const GValue *value;
2688
2689   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2690   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2691
2692   value = gst_structure_get_value (structure, field_name);
2693
2694   if (G_VALUE_TYPE (value) == G_TYPE_DOUBLE) {
2695     /* already fixed */
2696     return FALSE;
2697   } else if (G_VALUE_TYPE (value) == GST_TYPE_DOUBLE_RANGE) {
2698     double x;
2699
2700     x = gst_value_get_double_range_min (value);
2701     if (target < x)
2702       target = x;
2703     x = gst_value_get_double_range_max (value);
2704     if (target > x)
2705       target = x;
2706     gst_structure_set (structure, field_name, G_TYPE_DOUBLE, target, NULL);
2707     return TRUE;
2708   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2709     const GValue *list_value;
2710     int i, n;
2711     double best = 0;
2712     int best_index = -1;
2713
2714     n = gst_value_list_get_size (value);
2715     for (i = 0; i < n; i++) {
2716       list_value = gst_value_list_get_value (value, i);
2717       if (G_VALUE_TYPE (list_value) == G_TYPE_DOUBLE) {
2718         double x = gst_g_value_get_double_unchecked (list_value);
2719
2720         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
2721           best_index = i;
2722           best = x;
2723         }
2724       }
2725     }
2726     if (best_index != -1) {
2727       gst_structure_set (structure, field_name, G_TYPE_DOUBLE, best, NULL);
2728       return TRUE;
2729     }
2730     return FALSE;
2731   }
2732
2733   return FALSE;
2734
2735 }
2736
2737 /**
2738  * gst_structure_fixate_field_boolean:
2739  * @structure: a #GstStructure
2740  * @field_name: a field in @structure
2741  * @target: the target value of the fixation
2742  *
2743  * Fixates a #GstStructure by changing the given @field_name field to the given
2744  * @target boolean if that field is not fixed yet.
2745  *
2746  * Returns: %TRUE if the structure could be fixated
2747  */
2748 gboolean
2749 gst_structure_fixate_field_boolean (GstStructure * structure,
2750     const char *field_name, gboolean target)
2751 {
2752   const GValue *value;
2753
2754   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2755   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2756
2757   value = gst_structure_get_value (structure, field_name);
2758
2759   if (G_VALUE_TYPE (value) == G_TYPE_BOOLEAN) {
2760     /* already fixed */
2761     return FALSE;
2762   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2763     const GValue *list_value;
2764     int i, n;
2765     int best = 0;
2766     int best_index = -1;
2767
2768     n = gst_value_list_get_size (value);
2769     for (i = 0; i < n; i++) {
2770       list_value = gst_value_list_get_value (value, i);
2771       if (G_VALUE_TYPE (list_value) == G_TYPE_BOOLEAN) {
2772         gboolean x = gst_g_value_get_boolean_unchecked (list_value);
2773
2774         if (best_index == -1 || x == target) {
2775           best_index = i;
2776           best = x;
2777         }
2778       }
2779     }
2780     if (best_index != -1) {
2781       gst_structure_set (structure, field_name, G_TYPE_BOOLEAN, best, NULL);
2782       return TRUE;
2783     }
2784     return FALSE;
2785   }
2786
2787   return FALSE;
2788 }
2789
2790 /**
2791  * gst_structure_fixate_field_string:
2792  * @structure: a #GstStructure
2793  * @field_name: a field in @structure
2794  * @target: the target value of the fixation
2795  *
2796  * Fixates a #GstStructure by changing the given @field_name field to the given
2797  * @target string if that field is not fixed yet.
2798  *
2799  * Returns: %TRUE if the structure could be fixated
2800  */
2801 gboolean
2802 gst_structure_fixate_field_string (GstStructure * structure,
2803     const gchar * field_name, const gchar * target)
2804 {
2805   const GValue *value;
2806
2807   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2808   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2809
2810   value = gst_structure_get_value (structure, field_name);
2811
2812   if (G_VALUE_TYPE (value) == G_TYPE_STRING) {
2813     /* already fixed */
2814     return FALSE;
2815   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2816     const GValue *list_value;
2817     int i, n;
2818     const gchar *best = NULL;
2819     int best_index = -1;
2820
2821     n = gst_value_list_get_size (value);
2822     for (i = 0; i < n; i++) {
2823       list_value = gst_value_list_get_value (value, i);
2824       if (G_VALUE_TYPE (list_value) == G_TYPE_STRING) {
2825         const gchar *x = g_value_get_string (list_value);
2826
2827         if (best_index == -1 || g_str_equal (x, target)) {
2828           best_index = i;
2829           best = x;
2830         }
2831       }
2832     }
2833     if (best_index != -1) {
2834       gst_structure_set (structure, field_name, G_TYPE_STRING, best, NULL);
2835       return TRUE;
2836     }
2837     return FALSE;
2838   }
2839
2840   return FALSE;
2841 }
2842
2843 /**
2844  * gst_structure_fixate_field_nearest_fraction:
2845  * @structure: a #GstStructure
2846  * @field_name: a field in @structure
2847  * @target_numerator: The numerator of the target value of the fixation
2848  * @target_denominator: The denominator of the target value of the fixation
2849  *
2850  * Fixates a #GstStructure by changing the given field to the nearest
2851  * fraction to @target_numerator/@target_denominator that is a subset
2852  * of the existing field.
2853  *
2854  * Returns: %TRUE if the structure could be fixated
2855  */
2856 gboolean
2857 gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
2858     const char *field_name, const gint target_numerator,
2859     const gint target_denominator)
2860 {
2861   const GValue *value;
2862
2863   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2864   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2865   g_return_val_if_fail (target_denominator != 0, FALSE);
2866
2867   value = gst_structure_get_value (structure, field_name);
2868
2869   if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION) {
2870     /* already fixed */
2871     return FALSE;
2872   } else if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION_RANGE) {
2873     const GValue *x, *new_value;
2874     GValue target = { 0 };
2875     g_value_init (&target, GST_TYPE_FRACTION);
2876     gst_value_set_fraction (&target, target_numerator, target_denominator);
2877
2878     new_value = &target;
2879     x = gst_value_get_fraction_range_min (value);
2880     if (gst_value_compare (&target, x) == GST_VALUE_LESS_THAN)
2881       new_value = x;
2882     x = gst_value_get_fraction_range_max (value);
2883     if (gst_value_compare (&target, x) == GST_VALUE_GREATER_THAN)
2884       new_value = x;
2885
2886     gst_structure_set_value (structure, field_name, new_value);
2887     g_value_unset (&target);
2888     return TRUE;
2889   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2890     const GValue *list_value;
2891     int i, n;
2892     const GValue *best = NULL;
2893     gdouble target;
2894     gdouble cur_diff;
2895     gdouble best_diff = G_MAXDOUBLE;
2896
2897     target = (gdouble) target_numerator / (gdouble) target_denominator;
2898
2899     GST_DEBUG ("target %g, best %g", target, best_diff);
2900
2901     best = NULL;
2902
2903     n = gst_value_list_get_size (value);
2904     for (i = 0; i < n; i++) {
2905       list_value = gst_value_list_get_value (value, i);
2906       if (G_VALUE_TYPE (list_value) == GST_TYPE_FRACTION) {
2907         gint num, denom;
2908         gdouble list_double;
2909
2910         num = gst_value_get_fraction_numerator (list_value);
2911         denom = gst_value_get_fraction_denominator (list_value);
2912
2913         list_double = ((gdouble) num / (gdouble) denom);
2914         cur_diff = target - list_double;
2915
2916         GST_DEBUG ("curr diff %g, list %g", cur_diff, list_double);
2917
2918         if (cur_diff < 0)
2919           cur_diff = -cur_diff;
2920
2921         if (!best || cur_diff < best_diff) {
2922           GST_DEBUG ("new best %g", list_double);
2923           best = list_value;
2924           best_diff = cur_diff;
2925         }
2926       }
2927     }
2928     if (best != NULL) {
2929       gst_structure_set_value (structure, field_name, best);
2930       return TRUE;
2931     }
2932   }
2933
2934   return FALSE;
2935 }
2936
2937 static gboolean
2938 default_fixate (GQuark field_id, const GValue * value, gpointer data)
2939 {
2940   GstStructure *s = data;
2941   GValue v = { 0 };
2942
2943   if (gst_value_fixate (&v, value)) {
2944     gst_structure_id_take_value (s, field_id, &v);
2945   }
2946   return TRUE;
2947 }
2948
2949 /**
2950  * gst_structure_fixate_field:
2951  * @structure: a #GstStructure
2952  * @field_name: a field in @structure
2953  *
2954  * Fixates a #GstStructure by changing the given field with its fixated value.
2955  *
2956  * Returns: %TRUE if the structure field could be fixated
2957  */
2958 gboolean
2959 gst_structure_fixate_field (GstStructure * structure, const char *field_name)
2960 {
2961   GstStructureField *field;
2962
2963   g_return_val_if_fail (structure != NULL, FALSE);
2964   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2965
2966   if (!(field = gst_structure_get_field (structure, field_name)))
2967     return FALSE;
2968
2969   return default_fixate (field->name, &field->value, structure);
2970 }
2971
2972 /* our very own version of G_VALUE_LCOPY that allows NULL return locations
2973  * (useful for message parsing functions where the return location is user
2974  * supplied and the user may pass %NULL if the value isn't of interest) */
2975 #define GST_VALUE_LCOPY(value, var_args, flags, __error, fieldname)           \
2976 G_STMT_START {                                                                \
2977   const GValue *_value = (value);                                             \
2978   guint _flags = (flags);                                                     \
2979   GType _value_type = G_VALUE_TYPE (_value);                                  \
2980   GTypeValueTable *_vtable = g_type_value_table_peek (_value_type);           \
2981   const gchar *_lcopy_format = _vtable->lcopy_format;                         \
2982   GTypeCValue _cvalues[G_VALUE_COLLECT_FORMAT_MAX_LENGTH] = { { 0, }, };      \
2983   guint _n_values = 0;                                                        \
2984                                                                               \
2985   while (*_lcopy_format != '\0') {                                            \
2986     g_assert (*_lcopy_format == G_VALUE_COLLECT_POINTER);                     \
2987     _cvalues[_n_values++].v_pointer = va_arg ((var_args), gpointer);          \
2988     _lcopy_format++;                                                          \
2989   }                                                                           \
2990   if (_n_values == 2 && !!_cvalues[0].v_pointer != !!_cvalues[1].v_pointer) { \
2991     *(__error) = g_strdup_printf ("either all or none of the return "         \
2992         "locations for field '%s' need to be NULL", fieldname);               \
2993   } else if (_cvalues[0].v_pointer != NULL) {                                 \
2994     *(__error) = _vtable->lcopy_value (_value, _n_values, _cvalues, _flags);  \
2995   }                                                                           \
2996 } G_STMT_END
2997
2998 /**
2999  * gst_structure_get_valist:
3000  * @structure: a #GstStructure
3001  * @first_fieldname: the name of the first field to read
3002  * @args: variable arguments
3003  *
3004  * Parses the variable arguments and reads fields from @structure accordingly.
3005  * valist-variant of gst_structure_get(). Look at the documentation of
3006  * gst_structure_get() for more details.
3007  *
3008  * Returns: %TRUE, or %FALSE if there was a problem reading any of the fields
3009  */
3010 gboolean
3011 gst_structure_get_valist (const GstStructure * structure,
3012     const char *first_fieldname, va_list args)
3013 {
3014   const char *field_name;
3015   GType expected_type = G_TYPE_INVALID;
3016
3017   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
3018   g_return_val_if_fail (first_fieldname != NULL, FALSE);
3019
3020   field_name = first_fieldname;
3021   while (field_name) {
3022     const GValue *val = NULL;
3023     gchar *err = NULL;
3024
3025     expected_type = va_arg (args, GType);
3026
3027     val = gst_structure_get_value (structure, field_name);
3028
3029     if (val == NULL)
3030       goto no_such_field;
3031
3032     if (G_VALUE_TYPE (val) != expected_type)
3033       goto wrong_type;
3034
3035     GST_VALUE_LCOPY (val, args, 0, &err, field_name);
3036     if (err) {
3037       g_warning ("%s: %s", G_STRFUNC, err);
3038       g_free (err);
3039       return FALSE;
3040     }
3041
3042     field_name = va_arg (args, const gchar *);
3043   }
3044
3045   return TRUE;
3046
3047 /* ERRORS */
3048 no_such_field:
3049   {
3050     GST_INFO ("Expected field '%s' in structure: %" GST_PTR_FORMAT,
3051         field_name, structure);
3052     return FALSE;
3053   }
3054 wrong_type:
3055   {
3056     GST_INFO ("Expected field '%s' in structure to be of type '%s', but "
3057         "field was of type '%s': %" GST_PTR_FORMAT, field_name,
3058         GST_STR_NULL (g_type_name (expected_type)),
3059         G_VALUE_TYPE_NAME (gst_structure_get_value (structure, field_name)),
3060         structure);
3061     return FALSE;
3062   }
3063 }
3064
3065 /**
3066  * gst_structure_id_get_valist:
3067  * @structure: a #GstStructure
3068  * @first_field_id: the quark of the first field to read
3069  * @args: variable arguments
3070  *
3071  * Parses the variable arguments and reads fields from @structure accordingly.
3072  * valist-variant of gst_structure_id_get(). Look at the documentation of
3073  * gst_structure_id_get() for more details.
3074  *
3075  * Returns: %TRUE, or %FALSE if there was a problem reading any of the fields
3076  */
3077 gboolean
3078 gst_structure_id_get_valist (const GstStructure * structure,
3079     GQuark first_field_id, va_list args)
3080 {
3081   GQuark field_id;
3082   GType expected_type = G_TYPE_INVALID;
3083
3084   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
3085   g_return_val_if_fail (first_field_id != 0, FALSE);
3086
3087   field_id = first_field_id;
3088   while (field_id) {
3089     const GValue *val = NULL;
3090     gchar *err = NULL;
3091
3092     expected_type = va_arg (args, GType);
3093
3094     val = gst_structure_id_get_value (structure, field_id);
3095
3096     if (val == NULL)
3097       goto no_such_field;
3098
3099     if (G_VALUE_TYPE (val) != expected_type)
3100       goto wrong_type;
3101
3102     GST_VALUE_LCOPY (val, args, 0, &err, g_quark_to_string (field_id));
3103     if (err) {
3104       g_warning ("%s: %s", G_STRFUNC, err);
3105       g_free (err);
3106       return FALSE;
3107     }
3108
3109     field_id = va_arg (args, GQuark);
3110   }
3111
3112   return TRUE;
3113
3114 /* ERRORS */
3115 no_such_field:
3116   {
3117     GST_DEBUG ("Expected field '%s' in structure: %" GST_PTR_FORMAT,
3118         GST_STR_NULL (g_quark_to_string (field_id)), structure);
3119     return FALSE;
3120   }
3121 wrong_type:
3122   {
3123     GST_DEBUG ("Expected field '%s' in structure to be of type '%s', but "
3124         "field was of type '%s': %" GST_PTR_FORMAT,
3125         g_quark_to_string (field_id),
3126         GST_STR_NULL (g_type_name (expected_type)),
3127         G_VALUE_TYPE_NAME (gst_structure_id_get_value (structure, field_id)),
3128         structure);
3129     return FALSE;
3130   }
3131 }
3132
3133 /**
3134  * gst_structure_get:
3135  * @structure: a #GstStructure
3136  * @first_fieldname: the name of the first field to read
3137  * @...: variable arguments
3138  *
3139  * Parses the variable arguments and reads fields from @structure accordingly.
3140  * Variable arguments should be in the form field name, field type
3141  * (as a GType), pointer(s) to a variable(s) to hold the return value(s).
3142  * The last variable argument should be %NULL.
3143  *
3144  * For refcounted (mini)objects you will receive a new reference which
3145  * you must release with a suitable _unref() when no longer needed. For
3146  * strings and boxed types you will receive a copy which you will need to
3147  * release with either g_free() or the suitable function for the boxed type.
3148  *
3149  * Returns: %FALSE if there was a problem reading any of the fields (e.g.
3150  *     because the field requested did not exist, or was of a type other
3151  *     than the type specified), otherwise %TRUE.
3152  */
3153 gboolean
3154 gst_structure_get (const GstStructure * structure, const char *first_fieldname,
3155     ...)
3156 {
3157   gboolean ret;
3158   va_list args;
3159
3160   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
3161   g_return_val_if_fail (first_fieldname != NULL, FALSE);
3162
3163   va_start (args, first_fieldname);
3164   ret = gst_structure_get_valist (structure, first_fieldname, args);
3165   va_end (args);
3166
3167   return ret;
3168 }
3169
3170 /**
3171  * gst_structure_id_get:
3172  * @structure: a #GstStructure
3173  * @first_field_id: the quark of the first field to read
3174  * @...: variable arguments
3175  *
3176  * Parses the variable arguments and reads fields from @structure accordingly.
3177  * Variable arguments should be in the form field id quark, field type
3178  * (as a GType), pointer(s) to a variable(s) to hold the return value(s).
3179  * The last variable argument should be %NULL (technically it should be a
3180  * 0 quark, but we require %NULL so compilers that support it can check for
3181  * the %NULL terminator and warn if it's not there).
3182  *
3183  * This function is just like gst_structure_get() only that it is slightly
3184  * more efficient since it saves the string-to-quark lookup in the global
3185  * quark hashtable.
3186  *
3187  * For refcounted (mini)objects you will receive a new reference which
3188  * you must release with a suitable _unref() when no longer needed. For
3189  * strings and boxed types you will receive a copy which you will need to
3190  * release with either g_free() or the suitable function for the boxed type.
3191  *
3192  * Returns: %FALSE if there was a problem reading any of the fields (e.g.
3193  *     because the field requested did not exist, or was of a type other
3194  *     than the type specified), otherwise %TRUE.
3195  */
3196 gboolean
3197 gst_structure_id_get (const GstStructure * structure, GQuark first_field_id,
3198     ...)
3199 {
3200   gboolean ret;
3201   va_list args;
3202
3203   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
3204   g_return_val_if_fail (first_field_id != 0, FALSE);
3205
3206   va_start (args, first_field_id);
3207   ret = gst_structure_id_get_valist (structure, first_field_id, args);
3208   va_end (args);
3209
3210   return ret;
3211 }
3212
3213 static gboolean
3214 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
3215     gpointer data)
3216 {
3217   const GstStructure *struct1 = (const GstStructure *) data;
3218   const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
3219
3220   if (G_UNLIKELY (val1 == NULL))
3221     return FALSE;
3222   if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
3223     return TRUE;
3224   }
3225
3226   return FALSE;
3227 }
3228
3229 /**
3230  * gst_structure_is_equal:
3231  * @structure1: a #GstStructure.
3232  * @structure2: a #GstStructure.
3233  *
3234  * Tests if the two #GstStructure are equal.
3235  *
3236  * Returns: %TRUE if the two structures have the same name and field.
3237  **/
3238 gboolean
3239 gst_structure_is_equal (const GstStructure * structure1,
3240     const GstStructure * structure2)
3241 {
3242   g_return_val_if_fail (GST_IS_STRUCTURE (structure1), FALSE);
3243   g_return_val_if_fail (GST_IS_STRUCTURE (structure2), FALSE);
3244
3245   if (G_UNLIKELY (structure1 == structure2))
3246     return TRUE;
3247
3248   if (structure1->name != structure2->name) {
3249     return FALSE;
3250   }
3251   if (GST_STRUCTURE_FIELDS (structure1)->len !=
3252       GST_STRUCTURE_FIELDS (structure2)->len) {
3253     return FALSE;
3254   }
3255
3256   return gst_structure_foreach (structure1, gst_structure_is_equal_foreach,
3257       (gpointer) structure2);
3258 }
3259
3260
3261 typedef struct
3262 {
3263   GstStructure *dest;
3264   const GstStructure *intersect;
3265 }
3266 IntersectData;
3267
3268 static gboolean
3269 gst_structure_intersect_field1 (GQuark id, const GValue * val1, gpointer data)
3270 {
3271   IntersectData *idata = (IntersectData *) data;
3272   const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
3273
3274   if (G_UNLIKELY (val2 == NULL)) {
3275     gst_structure_id_set_value (idata->dest, id, val1);
3276   } else {
3277     GValue dest_value = { 0 };
3278     if (gst_value_intersect (&dest_value, val1, val2)) {
3279       gst_structure_id_take_value (idata->dest, id, &dest_value);
3280     } else {
3281       return FALSE;
3282     }
3283   }
3284   return TRUE;
3285 }
3286
3287 static gboolean
3288 gst_structure_intersect_field2 (GQuark id, const GValue * val1, gpointer data)
3289 {
3290   IntersectData *idata = (IntersectData *) data;
3291   const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
3292
3293   if (G_UNLIKELY (val2 == NULL)) {
3294     gst_structure_id_set_value (idata->dest, id, val1);
3295   }
3296   return TRUE;
3297 }
3298
3299 /**
3300  * gst_structure_intersect:
3301  * @struct1: a #GstStructure
3302  * @struct2: a #GstStructure
3303  *
3304  * Intersects @struct1 and @struct2 and returns the intersection.
3305  *
3306  * Returns: Intersection of @struct1 and @struct2
3307  */
3308 GstStructure *
3309 gst_structure_intersect (const GstStructure * struct1,
3310     const GstStructure * struct2)
3311 {
3312   IntersectData data;
3313
3314   g_assert (struct1 != NULL);
3315   g_assert (struct2 != NULL);
3316
3317   if (G_UNLIKELY (struct1->name != struct2->name))
3318     return NULL;
3319
3320   /* copy fields from struct1 which we have not in struct2 to target
3321    * intersect if we have the field in both */
3322   data.dest = gst_structure_new_id_empty (struct1->name);
3323   data.intersect = struct2;
3324   if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
3325               gst_structure_intersect_field1, &data)))
3326     goto error;
3327
3328   /* copy fields from struct2 which we have not in struct1 to target */
3329   data.intersect = struct1;
3330   if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
3331               gst_structure_intersect_field2, &data)))
3332     goto error;
3333
3334   return data.dest;
3335
3336 error:
3337   gst_structure_free (data.dest);
3338   return NULL;
3339 }
3340
3341 static gboolean
3342 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
3343     gpointer data)
3344 {
3345   GstStructure *other = (GstStructure *) data;
3346   const GValue *val2 = gst_structure_id_get_value (other, id);
3347
3348   if (G_LIKELY (val2)) {
3349     if (!gst_value_can_intersect (val1, val2)) {
3350       return FALSE;
3351     } else {
3352       gint eq = gst_value_compare (val1, val2);
3353
3354       if (eq == GST_VALUE_UNORDERED) {
3355         /* we need to try interseting */
3356         if (!gst_value_intersect (NULL, val1, val2)) {
3357           return FALSE;
3358         }
3359       } else if (eq != GST_VALUE_EQUAL) {
3360         return FALSE;
3361       }
3362     }
3363   }
3364   return TRUE;
3365 }
3366
3367 /**
3368  * gst_structure_can_intersect:
3369  * @struct1: a #GstStructure
3370  * @struct2: a #GstStructure
3371  *
3372  * Tries intersecting @struct1 and @struct2 and reports whether the result
3373  * would not be empty.
3374  *
3375  * Returns: %TRUE if intersection would not be empty
3376  */
3377 gboolean
3378 gst_structure_can_intersect (const GstStructure * struct1,
3379     const GstStructure * struct2)
3380 {
3381   g_return_val_if_fail (GST_IS_STRUCTURE (struct1), FALSE);
3382   g_return_val_if_fail (GST_IS_STRUCTURE (struct2), FALSE);
3383
3384   if (G_UNLIKELY (struct1->name != struct2->name))
3385     return FALSE;
3386
3387   /* tries to intersect if we have the field in both */
3388   return gst_structure_foreach ((GstStructure *) struct1,
3389       gst_caps_structure_can_intersect_field, (gpointer) struct2);
3390 }
3391
3392 static gboolean
3393 gst_caps_structure_is_superset_field (GQuark field_id, const GValue * value,
3394     gpointer user_data)
3395 {
3396   GstStructure *subset = user_data;
3397   const GValue *other;
3398   int comparison;
3399
3400   if (!(other = gst_structure_id_get_value (subset, field_id)))
3401     /* field is missing in the subset => no subset */
3402     return FALSE;
3403
3404   comparison = gst_value_compare (value, other);
3405
3406   /* equal values are subset */
3407   if (comparison == GST_VALUE_EQUAL)
3408     return TRUE;
3409
3410   /* ordered, but unequal, values are not */
3411   if (comparison != GST_VALUE_UNORDERED)
3412     return FALSE;
3413
3414   return gst_value_is_subset (other, value);
3415 }
3416
3417 /**
3418  * gst_structure_is_subset:
3419  * @subset: a #GstStructure
3420  * @superset: a potentially greater #GstStructure
3421  *
3422  * Checks if @subset is a subset of @superset, i.e. has the same
3423  * structure name and for all fields that are existing in @superset,
3424  * @subset has a value that is a subset of the value in @superset.
3425  *
3426  * Returns: %TRUE if @subset is a subset of @superset
3427  */
3428 gboolean
3429 gst_structure_is_subset (const GstStructure * subset,
3430     const GstStructure * superset)
3431 {
3432   if ((superset->name != subset->name) ||
3433       (gst_structure_n_fields (superset) > gst_structure_n_fields (subset)))
3434     return FALSE;
3435
3436   return gst_structure_foreach ((GstStructure *) superset,
3437       gst_caps_structure_is_superset_field, (gpointer) subset);
3438 }
3439
3440
3441 /**
3442  * gst_structure_fixate:
3443  * @structure: a #GstStructure
3444  *
3445  * Fixate all values in @structure using gst_value_fixate().
3446  * @structure will be modified in-place and should be writable.
3447  */
3448 void
3449 gst_structure_fixate (GstStructure * structure)
3450 {
3451   g_return_if_fail (GST_IS_STRUCTURE (structure));
3452
3453   gst_structure_foreach (structure, default_fixate, structure);
3454 }