2 * Copyright (C) 2003 David A. Schleef <ds@schleef.org>
4 * gststructure.c: lists of { GQuark, GValue } tuples
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.
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.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
23 * SECTION:gststructure
24 * @short_description: Generic structure containing fields of names and values
25 * @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery
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.
30 * In addition to the key/value pairs, a #GstStructure also has a name. The name
31 * starts with a letter and can be folled by letters, numbers and any of "/-_.:".
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. It
36 * provides a means to enforce mutability using the refcount of the parent
37 * with the gst_structure_set_parent_refcount() method.
39 * A #GstStructure can be created with gst_structure_empty_new() or
40 * gst_structure_new(), which both take a name and an optional set of
41 * key/value pairs along with the types of the values.
43 * Field values can be changed with gst_structure_set_value() or
44 * gst_structure_set().
46 * Field values can be retrieved with gst_structure_get_value() or the more
47 * convenient gst_structure_get_*() functions.
49 * Fields can be removed with gst_structure_remove_field() or
50 * gst_structure_remove_fields().
52 * Last reviewed on 2007-10-16 (0.10.15)
61 #include "gst_private.h"
64 #include <gobject/gvaluecollector.h>
66 typedef struct _GstStructureField GstStructureField;
68 struct _GstStructureField
74 #define GST_STRUCTURE_FIELD(structure, index) \
75 &g_array_index((structure)->fields, GstStructureField, (index))
77 #define IS_MUTABLE(structure) \
78 (!(structure)->parent_refcount || \
79 g_atomic_int_get ((structure)->parent_refcount) == 1)
81 #define IS_TAGLIST(structure) \
82 (structure->name == GST_QUARK (TAGLIST))
84 static void gst_structure_set_field (GstStructure * structure,
85 GstStructureField * field);
86 static GstStructureField *gst_structure_get_field (const GstStructure *
87 structure, const gchar * fieldname);
88 static GstStructureField *gst_structure_id_get_field (const GstStructure *
89 structure, GQuark field);
90 static void gst_structure_transform_to_string (const GValue * src_value,
92 static GstStructure *gst_structure_copy_conditional (const GstStructure *
94 static gboolean gst_structure_parse_value (gchar * str, gchar ** after,
95 GValue * value, GType default_type);
96 static gboolean gst_structure_parse_simple_string (gchar * s, gchar ** end);
99 gst_structure_get_type (void)
101 static GType gst_structure_type = 0;
103 if (G_UNLIKELY (gst_structure_type == 0)) {
104 gst_structure_type = g_boxed_type_register_static ("GstStructure",
105 (GBoxedCopyFunc) gst_structure_copy_conditional,
106 (GBoxedFreeFunc) gst_structure_free);
108 g_value_register_transform_func (gst_structure_type, G_TYPE_STRING,
109 gst_structure_transform_to_string);
112 return gst_structure_type;
115 static GstStructure *
116 gst_structure_id_empty_new_with_size (GQuark quark, guint prealloc)
118 GstStructure *structure;
120 structure = g_slice_new (GstStructure);
121 structure->type = gst_structure_get_type ();
122 structure->name = quark;
123 structure->parent_refcount = NULL;
125 g_array_sized_new (FALSE, FALSE, sizeof (GstStructureField), prealloc);
131 * gst_structure_id_empty_new:
132 * @quark: name of new structure
134 * Creates a new, empty #GstStructure with the given name as a GQuark.
136 * Returns: a new, empty #GstStructure
139 gst_structure_id_empty_new (GQuark quark)
141 g_return_val_if_fail (quark != 0, NULL);
143 return gst_structure_id_empty_new_with_size (quark, 0);
146 #ifndef G_DISABLE_CHECKS
148 gst_structure_validate_name (const gchar * name)
152 g_return_val_if_fail (name != NULL, FALSE);
154 /* FIXME 0.11: use g_ascii_isalpha() */
155 if (!g_ascii_isalnum (*name)) {
156 GST_WARNING ("Invalid character '%c' at offset 0 in structure name: %s",
161 /* FIXME 0.11: don't allow spaces */
162 /* FIXME: test name string more */
164 while (*s && (g_ascii_isalnum (*s) || strchr ("/-_.:+ ", *s) != NULL))
167 GST_WARNING ("Invalid character '%c' at offset %lu in structure name: %s",
168 *s, ((gulong) s - (gulong) name), name);
177 * gst_structure_empty_new:
178 * @name: name of new structure
180 * Creates a new, empty #GstStructure with the given @name.
182 * See gst_structure_set_name() for constraints on the @name parameter.
184 * Returns: a new, empty #GstStructure
187 gst_structure_empty_new (const gchar * name)
189 g_return_val_if_fail (gst_structure_validate_name (name), NULL);
191 return gst_structure_id_empty_new_with_size (g_quark_from_string (name), 0);
196 * @name: name of new structure
197 * @firstfield: name of first field to set
198 * @...: additional arguments
200 * Creates a new #GstStructure with the given name. Parses the
201 * list of variable arguments and sets fields to the values listed.
202 * Variable arguments should be passed as field name, field type,
203 * and value. Last variable argument should be NULL.
205 * Returns: a new #GstStructure
208 gst_structure_new (const gchar * name, const gchar * firstfield, ...)
210 GstStructure *structure;
213 g_return_val_if_fail (name != NULL, NULL);
215 va_start (varargs, firstfield);
217 structure = gst_structure_new_valist (name, firstfield, varargs);
225 * gst_structure_new_valist:
226 * @name: name of new structure
227 * @firstfield: name of first field to set
228 * @varargs: variable argument list
230 * Creates a new #GstStructure with the given @name. Structure fields
231 * are set according to the varargs in a manner similar to
232 * gst_structure_new().
234 * See gst_structure_set_name() for constraints on the @name parameter.
236 * Returns: a new #GstStructure
239 gst_structure_new_valist (const gchar * name,
240 const gchar * firstfield, va_list varargs)
242 GstStructure *structure;
244 g_return_val_if_fail (name != NULL, NULL);
246 structure = gst_structure_empty_new (name);
249 gst_structure_set_valist (structure, firstfield, varargs);
255 * gst_structure_set_parent_refcount:
256 * @structure: a #GstStructure
257 * @refcount: a pointer to the parent's refcount
259 * Sets the parent_refcount field of #GstStructure. This field is used to
260 * determine whether a structure is mutable or not. This function should only be
261 * called by code implementing parent objects of #GstStructure, as described in
262 * the MT Refcounting section of the design documents.
265 gst_structure_set_parent_refcount (GstStructure * structure, int *refcount)
267 g_return_if_fail (structure != NULL);
269 /* if we have a parent_refcount already, we can only clear
270 * if with a NULL refcount */
271 if (structure->parent_refcount)
272 g_return_if_fail (refcount == NULL);
274 g_return_if_fail (refcount != NULL);
276 structure->parent_refcount = refcount;
280 * gst_structure_copy:
281 * @structure: a #GstStructure to duplicate
283 * Duplicates a #GstStructure and all its fields and values.
285 * Returns: a new #GstStructure.
288 gst_structure_copy (const GstStructure * structure)
290 GstStructure *new_structure;
291 GstStructureField *field;
294 g_return_val_if_fail (structure != NULL, NULL);
297 gst_structure_id_empty_new_with_size (structure->name,
298 structure->fields->len);
300 for (i = 0; i < structure->fields->len; i++) {
301 GstStructureField new_field = { 0 };
303 field = GST_STRUCTURE_FIELD (structure, i);
305 new_field.name = field->name;
306 gst_value_init_and_copy (&new_field.value, &field->value);
307 g_array_append_val (new_structure->fields, new_field);
310 return new_structure;
314 * gst_structure_free:
315 * @structure: the #GstStructure to free
317 * Frees a #GstStructure and all its fields and values. The structure must not
318 * have a parent when this function is called.
321 gst_structure_free (GstStructure * structure)
323 GstStructureField *field;
326 g_return_if_fail (structure != NULL);
327 g_return_if_fail (structure->parent_refcount == NULL);
329 for (i = 0; i < structure->fields->len; i++) {
330 field = GST_STRUCTURE_FIELD (structure, i);
332 if (G_IS_VALUE (&field->value)) {
333 g_value_unset (&field->value);
336 g_array_free (structure->fields, TRUE);
338 memset (structure, 0xff, sizeof (GstStructure));
340 g_slice_free (GstStructure, structure);
344 * gst_structure_get_name:
345 * @structure: a #GstStructure
347 * Get the name of @structure as a string.
349 * Returns: the name of the structure.
352 gst_structure_get_name (const GstStructure * structure)
354 g_return_val_if_fail (structure != NULL, NULL);
356 return g_quark_to_string (structure->name);
360 * gst_structure_has_name:
361 * @structure: a #GstStructure
362 * @name: structure name to check for
364 * Checks if the structure has the given name
366 * Returns: TRUE if @name matches the name of the structure.
369 gst_structure_has_name (const GstStructure * structure, const gchar * name)
371 const gchar *structure_name;
373 g_return_val_if_fail (structure != NULL, FALSE);
374 g_return_val_if_fail (name != NULL, FALSE);
376 /* getting the string is cheap and comparing short strings is too
377 * should be faster than getting the quark for name and comparing the quarks
379 structure_name = g_quark_to_string (structure->name);
381 return (structure_name && strcmp (structure_name, name) == 0);
385 * gst_structure_get_name_id:
386 * @structure: a #GstStructure
388 * Get the name of @structure as a GQuark.
390 * Returns: the quark representing the name of the structure.
393 gst_structure_get_name_id (const GstStructure * structure)
395 g_return_val_if_fail (structure != NULL, 0);
397 return structure->name;
401 * gst_structure_set_name:
402 * @structure: a #GstStructure
403 * @name: the new name of the structure
405 * Sets the name of the structure to the given @name. The string
406 * provided is copied before being used. It must not be empty, start with a
407 * letter and can be followed by letters, numbers and any of "/-_.:".
410 gst_structure_set_name (GstStructure * structure, const gchar * name)
412 g_return_if_fail (structure != NULL);
413 g_return_if_fail (IS_MUTABLE (structure));
414 g_return_if_fail (gst_structure_validate_name (name));
416 structure->name = g_quark_from_string (name);
420 * gst_structure_id_set_value:
421 * @structure: a #GstStructure
422 * @field: a #GQuark representing a field
423 * @value: the new value of the field
425 * Sets the field with the given GQuark @field to @value. If the field
426 * does not exist, it is created. If the field exists, the previous
427 * value is replaced and freed.
430 gst_structure_id_set_value (GstStructure * structure,
431 GQuark field, const GValue * value)
433 GstStructureField gsfield = { 0, {0,} };
435 g_return_if_fail (structure != NULL);
436 g_return_if_fail (G_IS_VALUE (value));
437 g_return_if_fail (IS_MUTABLE (structure));
439 gsfield.name = field;
440 gst_value_init_and_copy (&gsfield.value, value);
442 gst_structure_set_field (structure, &gsfield);
446 * gst_structure_set_value:
447 * @structure: a #GstStructure
448 * @fieldname: the name of the field to set
449 * @value: the new value of the field
451 * Sets the field with the given name @field to @value. If the field
452 * does not exist, it is created. If the field exists, the previous
453 * value is replaced and freed.
456 gst_structure_set_value (GstStructure * structure,
457 const gchar * fieldname, const GValue * value)
459 g_return_if_fail (structure != NULL);
460 g_return_if_fail (fieldname != NULL);
461 g_return_if_fail (G_IS_VALUE (value));
462 g_return_if_fail (IS_MUTABLE (structure));
464 gst_structure_id_set_value (structure, g_quark_from_string (fieldname),
470 * @structure: a #GstStructure
471 * @fieldname: the name of the field to set
472 * @...: variable arguments
474 * Parses the variable arguments and sets fields accordingly.
475 * Variable arguments should be in the form field name, field type
476 * (as a GType), value(s). The last variable argument should be NULL.
479 gst_structure_set (GstStructure * structure, const gchar * field, ...)
483 g_return_if_fail (structure != NULL);
485 va_start (varargs, field);
487 gst_structure_set_valist (structure, field, varargs);
493 * gst_structure_set_valist:
494 * @structure: a #GstStructure
495 * @fieldname: the name of the field to set
496 * @varargs: variable arguments
498 * va_list form of gst_structure_set().
501 gst_structure_set_valist (GstStructure * structure,
502 const gchar * fieldname, va_list varargs)
507 g_return_if_fail (structure != NULL);
508 g_return_if_fail (IS_MUTABLE (structure));
511 GstStructureField field = { 0 };
513 field.name = g_quark_from_string (fieldname);
515 type = va_arg (varargs, GType);
517 if (type == G_TYPE_DATE) {
518 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
519 type = GST_TYPE_DATE;
522 g_value_init (&field.value, type);
523 G_VALUE_COLLECT (&field.value, varargs, 0, &err);
525 g_critical ("%s", err);
528 gst_structure_set_field (structure, &field);
530 fieldname = va_arg (varargs, gchar *);
535 * gst_structure_id_set:
536 * @structure: a #GstStructure
537 * @fieldname: the GQuark for the name of the field to set
538 * @...: variable arguments
540 * Identical to gst_structure_set, except that field names are
541 * passed using the GQuark for the field name. This allows more efficient
542 * setting of the structure if the caller already knows the associated
544 * The last variable argument must be NULL.
549 gst_structure_id_set (GstStructure * structure, GQuark field, ...)
553 g_return_if_fail (structure != NULL);
555 va_start (varargs, field);
556 gst_structure_id_set_valist (structure, field, varargs);
561 * gst_structure_id_set_valist:
562 * @structure: a #GstStructure
563 * @fieldname: the name of the field to set
564 * @varargs: variable arguments
566 * va_list form of gst_structure_id_set().
571 gst_structure_id_set_valist (GstStructure * structure,
572 GQuark fieldname, va_list varargs)
577 g_return_if_fail (structure != NULL);
578 g_return_if_fail (IS_MUTABLE (structure));
581 GstStructureField field = { 0 };
583 field.name = fieldname;
585 type = va_arg (varargs, GType);
587 if (type == G_TYPE_DATE) {
588 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
589 type = GST_TYPE_DATE;
592 g_value_init (&field.value, type);
593 G_VALUE_COLLECT (&field.value, varargs, 0, &err);
595 g_critical ("%s", err);
598 gst_structure_set_field (structure, &field);
600 fieldname = va_arg (varargs, GQuark);
605 * gst_structure_id_new:
606 * @name_quark: name of new structure
607 * @field_quark: the GQuark for the name of the field to set
608 * @...: variable arguments
610 * Creates a new #GstStructure with the given name as a GQuark, followed by
611 * fieldname quark, GType, argument(s) "triplets" in the same format as
612 * gst_structure_id_set(). Basically a convenience wrapper around
613 * gst_structure_id_empty_new() and gst_structure_id_set().
615 * The last variable argument must be NULL (or 0).
617 * Returns: a new #GstStructure
622 gst_structure_id_new (GQuark name_quark, GQuark field_quark, ...)
627 g_return_val_if_fail (name_quark != 0, NULL);
628 g_return_val_if_fail (field_quark != 0, NULL);
630 s = gst_structure_id_empty_new (name_quark);
632 va_start (varargs, field_quark);
633 gst_structure_id_set_valist (s, field_quark, varargs);
639 /* If the structure currently contains a field with the same name, it is
640 * replaced with the provided field. Otherwise, the field is added to the
641 * structure. The field's value is not deeply copied.
644 gst_structure_set_field (GstStructure * structure, GstStructureField * field)
646 GstStructureField *f;
649 if (G_UNLIKELY (G_VALUE_HOLDS_STRING (&field->value))) {
652 s = g_value_get_string (&field->value);
653 /* only check for NULL strings in taglists, as they are allowed in message
654 * structs, e.g. error message debug strings */
655 if (G_UNLIKELY (s == NULL && IS_TAGLIST (structure))) {
656 g_warning ("Trying to set NULL string on field '%s' on taglist. "
657 "Please file a bug.", g_quark_to_string (field->name));
658 g_value_unset (&field->value);
660 } else if (G_UNLIKELY (s != NULL && *s == '\0')) {
661 /* empty strings never make sense */
662 g_warning ("Trying to set empty string on %s field '%s'. Please file a "
663 "bug.", IS_TAGLIST (structure) ? "taglist" : "structure",
664 g_quark_to_string (field->name));
665 g_value_unset (&field->value);
667 } else if (G_UNLIKELY (s != NULL && !g_utf8_validate (s, -1, NULL))) {
668 g_warning ("Trying to set string on %s field '%s', but string is not "
669 "valid UTF-8. Please file a bug.",
670 IS_TAGLIST (structure) ? "taglist" : "structure",
671 g_quark_to_string (field->name));
672 g_value_unset (&field->value);
677 for (i = 0; i < structure->fields->len; i++) {
678 f = GST_STRUCTURE_FIELD (structure, i);
680 if (f->name == field->name) {
681 g_value_unset (&f->value);
682 memcpy (f, field, sizeof (GstStructureField));
687 g_array_append_val (structure->fields, *field);
690 /* If there is no field with the given ID, NULL is returned.
692 static GstStructureField *
693 gst_structure_id_get_field (const GstStructure * structure, GQuark field_id)
695 GstStructureField *field;
698 g_return_val_if_fail (structure != NULL, NULL);
700 for (i = 0; i < structure->fields->len; i++) {
701 field = GST_STRUCTURE_FIELD (structure, i);
703 if (field->name == field_id)
710 /* If there is no field with the given ID, NULL is returned.
712 static GstStructureField *
713 gst_structure_get_field (const GstStructure * structure,
714 const gchar * fieldname)
716 g_return_val_if_fail (structure != NULL, NULL);
717 g_return_val_if_fail (fieldname != NULL, NULL);
719 return gst_structure_id_get_field (structure,
720 g_quark_from_string (fieldname));
724 * gst_structure_get_value:
725 * @structure: a #GstStructure
726 * @fieldname: the name of the field to get
728 * Get the value of the field with name @fieldname.
730 * Returns: the #GValue corresponding to the field with the given name.
733 gst_structure_get_value (const GstStructure * structure,
734 const gchar * fieldname)
736 GstStructureField *field;
738 g_return_val_if_fail (structure != NULL, NULL);
739 g_return_val_if_fail (fieldname != NULL, NULL);
741 field = gst_structure_get_field (structure, fieldname);
745 return &field->value;
749 * gst_structure_id_get_value:
750 * @structure: a #GstStructure
751 * @field: the #GQuark of the field to get
753 * Get the value of the field with GQuark @field.
755 * Returns: the #GValue corresponding to the field with the given name
759 gst_structure_id_get_value (const GstStructure * structure, GQuark field)
761 GstStructureField *gsfield;
763 g_return_val_if_fail (structure != NULL, NULL);
765 gsfield = gst_structure_id_get_field (structure, field);
769 return &gsfield->value;
773 * gst_structure_remove_field:
774 * @structure: a #GstStructure
775 * @fieldname: the name of the field to remove
777 * Removes the field with the given name. If the field with the given
778 * name does not exist, the structure is unchanged.
781 gst_structure_remove_field (GstStructure * structure, const gchar * fieldname)
783 GstStructureField *field;
787 g_return_if_fail (structure != NULL);
788 g_return_if_fail (fieldname != NULL);
789 g_return_if_fail (IS_MUTABLE (structure));
791 id = g_quark_from_string (fieldname);
793 for (i = 0; i < structure->fields->len; i++) {
794 field = GST_STRUCTURE_FIELD (structure, i);
796 if (field->name == id) {
797 if (G_IS_VALUE (&field->value)) {
798 g_value_unset (&field->value);
800 structure->fields = g_array_remove_index (structure->fields, i);
807 * gst_structure_remove_fields:
808 * @structure: a #GstStructure
809 * @fieldname: the name of the field to remove
810 * @...: NULL-terminated list of more fieldnames to remove
812 * Removes the fields with the given names. If a field does not exist, the
813 * argument is ignored.
816 gst_structure_remove_fields (GstStructure * structure,
817 const gchar * fieldname, ...)
821 g_return_if_fail (structure != NULL);
822 g_return_if_fail (fieldname != NULL);
823 /* mutability checked in remove_field */
825 va_start (varargs, fieldname);
827 gst_structure_remove_fields_valist (structure, fieldname, varargs);
833 * gst_structure_remove_fields_valist:
834 * @structure: a #GstStructure
835 * @fieldname: the name of the field to remove
836 * @varargs: NULL-terminated list of more fieldnames to remove
838 * va_list form of gst_structure_remove_fields().
841 gst_structure_remove_fields_valist (GstStructure * structure,
842 const gchar * fieldname, va_list varargs)
844 gchar *field = (gchar *) fieldname;
846 g_return_if_fail (structure != NULL);
847 g_return_if_fail (fieldname != NULL);
848 /* mutability checked in remove_field */
851 gst_structure_remove_field (structure, field);
852 field = va_arg (varargs, char *);
857 * gst_structure_remove_all_fields:
858 * @structure: a #GstStructure
860 * Removes all fields in a GstStructure.
863 gst_structure_remove_all_fields (GstStructure * structure)
865 GstStructureField *field;
868 g_return_if_fail (structure != NULL);
869 g_return_if_fail (IS_MUTABLE (structure));
871 for (i = structure->fields->len - 1; i >= 0; i--) {
872 field = GST_STRUCTURE_FIELD (structure, i);
874 if (G_IS_VALUE (&field->value)) {
875 g_value_unset (&field->value);
877 structure->fields = g_array_remove_index (structure->fields, i);
882 * gst_structure_get_field_type:
883 * @structure: a #GstStructure
884 * @fieldname: the name of the field
886 * Finds the field with the given name, and returns the type of the
887 * value it contains. If the field is not found, G_TYPE_INVALID is
890 * Returns: the #GValue of the field
893 gst_structure_get_field_type (const GstStructure * structure,
894 const gchar * fieldname)
896 GstStructureField *field;
898 g_return_val_if_fail (structure != NULL, G_TYPE_INVALID);
899 g_return_val_if_fail (fieldname != NULL, G_TYPE_INVALID);
901 field = gst_structure_get_field (structure, fieldname);
903 return G_TYPE_INVALID;
905 return G_VALUE_TYPE (&field->value);
909 * gst_structure_n_fields:
910 * @structure: a #GstStructure
912 * Get the number of fields in the structure.
914 * Returns: the number of fields in the structure
917 gst_structure_n_fields (const GstStructure * structure)
919 g_return_val_if_fail (structure != NULL, 0);
921 return structure->fields->len;
925 * gst_structure_nth_field_name:
926 * @structure: a #GstStructure
927 * @index: the index to get the name of
929 * Get the name of the given field number, counting from 0 onwards.
931 * Returns: the name of the given field number
934 gst_structure_nth_field_name (const GstStructure * structure, guint index)
936 GstStructureField *field;
938 g_return_val_if_fail (structure != NULL, NULL);
939 g_return_val_if_fail (index < structure->fields->len, NULL);
941 field = GST_STRUCTURE_FIELD (structure, index);
943 return g_quark_to_string (field->name);
947 * gst_structure_foreach:
948 * @structure: a #GstStructure
949 * @func: a function to call for each field
950 * @user_data: private data
952 * Calls the provided function once for each field in the #GstStructure. The
953 * function must not modify the fields. Also see gst_structure_map_in_place().
955 * Returns: TRUE if the supplied function returns TRUE For each of the fields,
959 gst_structure_foreach (const GstStructure * structure,
960 GstStructureForeachFunc func, gpointer user_data)
963 GstStructureField *field;
966 g_return_val_if_fail (structure != NULL, FALSE);
967 g_return_val_if_fail (func != NULL, FALSE);
969 for (i = 0; i < structure->fields->len; i++) {
970 field = GST_STRUCTURE_FIELD (structure, i);
972 ret = func (field->name, &field->value, user_data);
981 * gst_structure_map_in_place:
982 * @structure: a #GstStructure
983 * @func: a function to call for each field
984 * @user_data: private data
986 * Calls the provided function once for each field in the #GstStructure. In
987 * contrast to gst_structure_foreach(), the function may modify but not delete the
988 * fields. The structure must be mutable.
990 * Returns: TRUE if the supplied function returns TRUE For each of the fields,
994 gst_structure_map_in_place (GstStructure * structure,
995 GstStructureMapFunc func, gpointer user_data)
998 GstStructureField *field;
1001 g_return_val_if_fail (structure != NULL, FALSE);
1002 g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1003 g_return_val_if_fail (func != NULL, FALSE);
1005 for (i = 0; i < structure->fields->len; i++) {
1006 field = GST_STRUCTURE_FIELD (structure, i);
1008 ret = func (field->name, &field->value, user_data);
1017 * gst_structure_has_field:
1018 * @structure: a #GstStructure
1019 * @fieldname: the name of a field
1021 * Check if @structure contains a field named @fieldname.
1023 * Returns: TRUE if the structure contains a field with the given name
1026 gst_structure_has_field (const GstStructure * structure,
1027 const gchar * fieldname)
1029 GstStructureField *field;
1031 g_return_val_if_fail (structure != NULL, 0);
1032 g_return_val_if_fail (fieldname != NULL, 0);
1034 field = gst_structure_get_field (structure, fieldname);
1036 return (field != NULL);
1040 * gst_structure_has_field_typed:
1041 * @structure: a #GstStructure
1042 * @fieldname: the name of a field
1043 * @type: the type of a value
1045 * Check if @structure contains a field named @fieldname and with GType @type.
1047 * Returns: TRUE if the structure contains a field with the given name and type
1050 gst_structure_has_field_typed (const GstStructure * structure,
1051 const gchar * fieldname, GType type)
1053 GstStructureField *field;
1055 g_return_val_if_fail (structure != NULL, 0);
1056 g_return_val_if_fail (fieldname != NULL, 0);
1058 field = gst_structure_get_field (structure, fieldname);
1062 return (G_VALUE_TYPE (&field->value) == type);
1066 /* utility functions */
1069 * gst_structure_get_boolean:
1070 * @structure: a #GstStructure
1071 * @fieldname: the name of a field
1072 * @value: a pointer to a #gboolean to set
1074 * Sets the boolean pointed to by @value corresponding to the value of the
1075 * given field. Caller is responsible for making sure the field exists
1076 * and has the correct type.
1078 * Returns: TRUE if the value could be set correctly. If there was no field
1079 * with @fieldname or the existing field did not contain a boolean, this
1080 * function returns FALSE.
1083 gst_structure_get_boolean (const GstStructure * structure,
1084 const gchar * fieldname, gboolean * value)
1086 GstStructureField *field;
1088 g_return_val_if_fail (structure != NULL, FALSE);
1089 g_return_val_if_fail (fieldname != NULL, FALSE);
1091 field = gst_structure_get_field (structure, fieldname);
1095 if (!G_VALUE_HOLDS_BOOLEAN (&field->value))
1098 *value = g_value_get_boolean (&field->value);
1104 * gst_structure_get_int:
1105 * @structure: a #GstStructure
1106 * @fieldname: the name of a field
1107 * @value: a pointer to an int to set
1109 * Sets the int pointed to by @value corresponding to the value of the
1110 * given field. Caller is responsible for making sure the field exists
1111 * and has the correct type.
1113 * Returns: %TRUE if the value could be set correctly. If there was no field
1114 * with @fieldname or the existing field did not contain an int, this function
1118 gst_structure_get_int (const GstStructure * structure,
1119 const gchar * fieldname, gint * value)
1121 GstStructureField *field;
1123 g_return_val_if_fail (structure != NULL, FALSE);
1124 g_return_val_if_fail (fieldname != NULL, FALSE);
1125 g_return_val_if_fail (value != NULL, FALSE);
1127 field = gst_structure_get_field (structure, fieldname);
1131 if (!G_VALUE_HOLDS_INT (&field->value))
1134 *value = g_value_get_int (&field->value);
1140 * gst_structure_get_uint:
1141 * @structure: a #GstStructure
1142 * @fieldname: the name of a field
1143 * @value: a pointer to a uint to set
1145 * Sets the uint pointed to by @value corresponding to the value of the
1146 * given field. Caller is responsible for making sure the field exists
1147 * and has the correct type.
1149 * Returns: %TRUE if the value could be set correctly. If there was no field
1150 * with @fieldname or the existing field did not contain a uint, this function
1156 gst_structure_get_uint (const GstStructure * structure,
1157 const gchar * fieldname, guint * value)
1159 GstStructureField *field;
1161 g_return_val_if_fail (structure != NULL, FALSE);
1162 g_return_val_if_fail (fieldname != NULL, FALSE);
1163 g_return_val_if_fail (value != NULL, FALSE);
1165 field = gst_structure_get_field (structure, fieldname);
1169 if (!G_VALUE_HOLDS_UINT (&field->value))
1172 *value = g_value_get_uint (&field->value);
1178 * gst_structure_get_fourcc:
1179 * @structure: a #GstStructure
1180 * @fieldname: the name of a field
1181 * @value: a pointer to a #GstFourcc to set
1183 * Sets the #GstFourcc pointed to by @value corresponding to the value of the
1184 * given field. Caller is responsible for making sure the field exists
1185 * and has the correct type.
1187 * Returns: TRUE if the value could be set correctly. If there was no field
1188 * with @fieldname or the existing field did not contain a fourcc, this function
1192 gst_structure_get_fourcc (const GstStructure * structure,
1193 const gchar * fieldname, guint32 * value)
1195 GstStructureField *field;
1197 g_return_val_if_fail (structure != NULL, FALSE);
1198 g_return_val_if_fail (fieldname != NULL, FALSE);
1199 g_return_val_if_fail (value != NULL, FALSE);
1201 field = gst_structure_get_field (structure, fieldname);
1205 if (!GST_VALUE_HOLDS_FOURCC (&field->value))
1208 *value = gst_value_get_fourcc (&field->value);
1214 * gst_structure_get_date:
1215 * @structure: a #GstStructure
1216 * @fieldname: the name of a field
1217 * @value: a pointer to a #GDate to set
1219 * Sets the date pointed to by @value corresponding to the date of the
1220 * given field. Caller is responsible for making sure the field exists
1221 * and has the correct type.
1223 * Returns: TRUE if the value could be set correctly. If there was no field
1224 * with @fieldname or the existing field did not contain a data, this function
1228 gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
1231 GstStructureField *field;
1233 g_return_val_if_fail (structure != NULL, FALSE);
1234 g_return_val_if_fail (fieldname != NULL, FALSE);
1235 g_return_val_if_fail (value != NULL, FALSE);
1237 field = gst_structure_get_field (structure, fieldname);
1241 if (!GST_VALUE_HOLDS_DATE (&field->value))
1244 *value = g_value_dup_boxed (&field->value);
1250 * gst_structure_get_clock_time:
1251 * @structure: a #GstStructure
1252 * @fieldname: the name of a field
1253 * @value: a pointer to a #GstClockTime to set
1255 * Sets the clock time pointed to by @value corresponding to the clock time
1256 * of the given field. Caller is responsible for making sure the field exists
1257 * and has the correct type.
1259 * Returns: TRUE if the value could be set correctly. If there was no field
1260 * with @fieldname or the existing field did not contain a #GstClockTime, this
1261 * function returns FALSE.
1264 gst_structure_get_clock_time (const GstStructure * structure,
1265 const gchar * fieldname, GstClockTime * value)
1267 GstStructureField *field;
1269 g_return_val_if_fail (structure != NULL, FALSE);
1270 g_return_val_if_fail (fieldname != NULL, FALSE);
1271 g_return_val_if_fail (value != NULL, FALSE);
1273 field = gst_structure_get_field (structure, fieldname);
1277 if (!G_VALUE_HOLDS_UINT64 (&field->value))
1280 *value = g_value_get_uint64 (&field->value);
1286 * gst_structure_get_double:
1287 * @structure: a #GstStructure
1288 * @fieldname: the name of a field
1289 * @value: a pointer to a #GstFourcc to set
1291 * Sets the double pointed to by @value corresponding to the value of the
1292 * given field. Caller is responsible for making sure the field exists
1293 * and has the correct type.
1295 * Returns: TRUE if the value could be set correctly. If there was no field
1296 * with @fieldname or the existing field did not contain a double, this
1297 * function returns FALSE.
1300 gst_structure_get_double (const GstStructure * structure,
1301 const gchar * fieldname, gdouble * value)
1303 GstStructureField *field;
1305 g_return_val_if_fail (structure != NULL, FALSE);
1306 g_return_val_if_fail (fieldname != NULL, FALSE);
1307 g_return_val_if_fail (value != NULL, FALSE);
1309 field = gst_structure_get_field (structure, fieldname);
1313 if (!G_VALUE_HOLDS_DOUBLE (&field->value))
1316 *value = g_value_get_double (&field->value);
1322 * gst_structure_get_string:
1323 * @structure: a #GstStructure
1324 * @fieldname: the name of a field
1326 * Finds the field corresponding to @fieldname, and returns the string
1327 * contained in the field's value. Caller is responsible for making
1328 * sure the field exists and has the correct type.
1330 * The string should not be modified, and remains valid until the next
1331 * call to a gst_structure_*() function with the given structure.
1333 * Returns: a pointer to the string or NULL when the field did not exist
1334 * or did not contain a string.
1337 gst_structure_get_string (const GstStructure * structure,
1338 const gchar * fieldname)
1340 GstStructureField *field;
1342 g_return_val_if_fail (structure != NULL, NULL);
1343 g_return_val_if_fail (fieldname != NULL, NULL);
1345 field = gst_structure_get_field (structure, fieldname);
1349 if (!G_VALUE_HOLDS_STRING (&field->value))
1352 return g_value_get_string (&field->value);
1356 * gst_structure_get_enum:
1357 * @structure: a #GstStructure
1358 * @fieldname: the name of a field
1359 * @enumtype: the enum type of a field
1360 * @value: a pointer to an int to set
1362 * Sets the int pointed to by @value corresponding to the value of the
1363 * given field. Caller is responsible for making sure the field exists,
1364 * has the correct type and that the enumtype is correct.
1366 * Returns: TRUE if the value could be set correctly. If there was no field
1367 * with @fieldname or the existing field did not contain an enum of the given
1368 * type, this function returns FALSE.
1371 gst_structure_get_enum (const GstStructure * structure,
1372 const gchar * fieldname, GType enumtype, gint * value)
1374 GstStructureField *field;
1376 g_return_val_if_fail (structure != NULL, FALSE);
1377 g_return_val_if_fail (fieldname != NULL, FALSE);
1378 g_return_val_if_fail (enumtype != G_TYPE_INVALID, FALSE);
1379 g_return_val_if_fail (value != NULL, FALSE);
1381 field = gst_structure_get_field (structure, fieldname);
1385 if (!G_VALUE_HOLDS_ENUM (&field->value))
1387 if (!G_TYPE_CHECK_VALUE_TYPE (&field->value, enumtype))
1390 *value = g_value_get_enum (&field->value);
1396 * gst_structure_get_fraction:
1397 * @structure: a #GstStructure
1398 * @fieldname: the name of a field
1399 * @value_numerator: a pointer to an int to set
1400 * @value_denominator: a pointer to an int to set
1402 * Sets the integers pointed to by @value_numerator and @value_denominator
1403 * corresponding to the value of the given field. Caller is responsible
1404 * for making sure the field exists and has the correct type.
1406 * Returns: TRUE if the values could be set correctly. If there was no field
1407 * with @fieldname or the existing field did not contain a GstFraction, this
1408 * function returns FALSE.
1411 gst_structure_get_fraction (const GstStructure * structure,
1412 const gchar * fieldname, gint * value_numerator, gint * value_denominator)
1414 GstStructureField *field;
1416 g_return_val_if_fail (structure != NULL, FALSE);
1417 g_return_val_if_fail (fieldname != NULL, FALSE);
1418 g_return_val_if_fail (value_numerator != NULL, FALSE);
1419 g_return_val_if_fail (value_denominator != NULL, FALSE);
1421 field = gst_structure_get_field (structure, fieldname);
1425 if (!GST_VALUE_HOLDS_FRACTION (&field->value))
1428 *value_numerator = gst_value_get_fraction_numerator (&field->value);
1429 *value_denominator = gst_value_get_fraction_denominator (&field->value);
1434 typedef struct _GstStructureAbbreviation
1439 GstStructureAbbreviation;
1441 /* return a copy of an array of GstStructureAbbreviation containing all the
1442 * known type_string, GType maps, including abbreviations for common types */
1443 static GstStructureAbbreviation *
1444 gst_structure_get_abbrs (gint * n_abbrs)
1446 static GstStructureAbbreviation *abbrs = NULL;
1447 static gint num = 0;
1449 if (abbrs == NULL) {
1450 /* dynamically generate the array */
1451 GstStructureAbbreviation dyn_abbrs[] = {
1456 {"float", G_TYPE_FLOAT}
1460 {"double", G_TYPE_DOUBLE}
1462 {"d", G_TYPE_DOUBLE}
1464 {"buffer", GST_TYPE_BUFFER}
1466 {"fourcc", GST_TYPE_FOURCC}
1468 {"4", GST_TYPE_FOURCC}
1470 {"fraction", GST_TYPE_FRACTION}
1472 {"boolean", G_TYPE_BOOLEAN}
1474 {"bool", G_TYPE_BOOLEAN}
1476 {"b", G_TYPE_BOOLEAN}
1478 {"string", G_TYPE_STRING}
1480 {"str", G_TYPE_STRING}
1482 {"s", G_TYPE_STRING}
1484 {"structure", GST_TYPE_STRUCTURE}
1486 num = G_N_ELEMENTS (dyn_abbrs);
1487 /* permanently allocate and copy the array now */
1488 abbrs = g_new0 (GstStructureAbbreviation, num);
1489 memcpy (abbrs, dyn_abbrs, sizeof (GstStructureAbbreviation) * num);
1496 /* given a type_name that could be a type abbreviation or a registered GType,
1497 * return a matching GType */
1499 gst_structure_gtype_from_abbr (const char *type_name)
1502 GstStructureAbbreviation *abbrs;
1505 g_return_val_if_fail (type_name != NULL, G_TYPE_INVALID);
1507 abbrs = gst_structure_get_abbrs (&n_abbrs);
1509 for (i = 0; i < n_abbrs; i++) {
1510 if (strcmp (type_name, abbrs[i].type_name) == 0) {
1511 return abbrs[i].type;
1515 /* this is the fallback */
1516 return g_type_from_name (type_name);
1520 gst_structure_to_abbr (GType type)
1523 GstStructureAbbreviation *abbrs;
1526 g_return_val_if_fail (type != G_TYPE_INVALID, NULL);
1528 abbrs = gst_structure_get_abbrs (&n_abbrs);
1530 for (i = 0; i < n_abbrs; i++) {
1531 if (type == abbrs[i].type) {
1532 return abbrs[i].type_name;
1536 return g_type_name (type);
1540 gst_structure_value_get_generic_type (GValue * val)
1542 if (G_VALUE_TYPE (val) == GST_TYPE_LIST
1543 || G_VALUE_TYPE (val) == GST_TYPE_ARRAY) {
1544 GArray *array = g_value_peek_pointer (val);
1546 if (array->len > 0) {
1547 GValue *value = &g_array_index (array, GValue, 0);
1549 return gst_structure_value_get_generic_type (value);
1553 } else if (G_VALUE_TYPE (val) == GST_TYPE_INT_RANGE) {
1555 } else if (G_VALUE_TYPE (val) == GST_TYPE_DOUBLE_RANGE) {
1556 return G_TYPE_DOUBLE;
1557 } else if (G_VALUE_TYPE (val) == GST_TYPE_FRACTION_RANGE) {
1558 return GST_TYPE_FRACTION;
1560 return G_VALUE_TYPE (val);
1564 priv_gst_structure_append_to_gstring (const GstStructure * structure,
1567 GstStructureField *field;
1570 g_return_val_if_fail (s != NULL, FALSE);
1572 g_string_append (s, g_quark_to_string (structure->name));
1573 for (i = 0; i < structure->fields->len; i++) {
1577 field = GST_STRUCTURE_FIELD (structure, i);
1579 t = gst_value_serialize (&field->value);
1580 type = gst_structure_value_get_generic_type (&field->value);
1582 g_string_append_len (s, ", ", 2);
1583 /* FIXME: do we need to escape fieldnames? */
1584 g_string_append (s, g_quark_to_string (field->name));
1585 g_string_append_len (s, "=(", 2);
1586 g_string_append (s, gst_structure_to_abbr (type));
1587 g_string_append_c (s, ')');
1588 g_string_append (s, GST_STR_NULL (t));
1592 g_string_append_c (s, ';');
1597 * gst_structure_to_string:
1598 * @structure: a #GstStructure
1600 * Converts @structure to a human-readable string representation.
1602 * For debugging purposes its easier to do something like this:
1604 * GST_LOG ("structure is %" GST_PTR_FORMAT, structure);
1606 * This prints the structure in human readble form.
1608 * Returns: a pointer to string allocated by g_malloc(). g_free() after
1612 gst_structure_to_string (const GstStructure * structure)
1616 /* NOTE: This function is potentially called by the debug system,
1617 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1618 * should be careful to avoid recursion. This includes any functions
1619 * called by gst_structure_to_string. In particular, calls should
1620 * not use the GST_PTR_FORMAT extension. */
1622 g_return_val_if_fail (structure != NULL, NULL);
1624 /* we estimate a minimum size based on the number of fields in order to
1625 * avoid unnecessary reallocs within GString */
1626 s = g_string_sized_new (STRUCTURE_ESTIMATED_STRING_LEN (structure));
1627 priv_gst_structure_append_to_gstring (structure, s);
1628 return g_string_free (s, FALSE);
1632 * r will still point to the string. if end == next, the string will not be
1633 * null-terminated. In all other cases it will be.
1634 * end = pointer to char behind end of string, next = pointer to start of
1636 * THIS FUNCTION MODIFIES THE STRING AND DETECTS INSIDE A NONTERMINATED STRING
1639 gst_structure_parse_string (gchar * s, gchar ** end, gchar ** next)
1649 ret = gst_structure_parse_simple_string (s, end);
1678 gst_structure_parse_range (gchar * s, gchar ** after, GValue * value,
1681 GValue value1 = { 0 };
1682 GValue value2 = { 0 };
1690 ret = gst_structure_parse_value (s, &s, &value1, type);
1694 while (g_ascii_isspace (*s))
1701 while (g_ascii_isspace (*s))
1704 ret = gst_structure_parse_value (s, &s, &value2, type);
1708 while (g_ascii_isspace (*s))
1715 if (G_VALUE_TYPE (&value1) != G_VALUE_TYPE (&value2))
1718 if (G_VALUE_TYPE (&value1) == G_TYPE_DOUBLE) {
1719 range_type = GST_TYPE_DOUBLE_RANGE;
1720 g_value_init (value, range_type);
1721 gst_value_set_double_range (value, g_value_get_double (&value1),
1722 g_value_get_double (&value2));
1723 } else if (G_VALUE_TYPE (&value1) == G_TYPE_INT) {
1724 range_type = GST_TYPE_INT_RANGE;
1725 g_value_init (value, range_type);
1726 gst_value_set_int_range (value, g_value_get_int (&value1),
1727 g_value_get_int (&value2));
1728 } else if (G_VALUE_TYPE (&value1) == GST_TYPE_FRACTION) {
1729 range_type = GST_TYPE_FRACTION_RANGE;
1730 g_value_init (value, range_type);
1731 gst_value_set_fraction_range (value, &value1, &value2);
1741 gst_structure_parse_any_list (gchar * s, gchar ** after, GValue * value,
1742 GType type, GType list_type, char begin, char end)
1744 GValue list_value = { 0 };
1748 g_value_init (value, list_type);
1749 array = g_value_peek_pointer (value);
1755 while (g_ascii_isspace (*s))
1763 ret = gst_structure_parse_value (s, &s, &list_value, type);
1767 g_array_append_val (array, list_value);
1769 while (g_ascii_isspace (*s))
1777 while (g_ascii_isspace (*s))
1780 memset (&list_value, 0, sizeof (list_value));
1781 ret = gst_structure_parse_value (s, &s, &list_value, type);
1785 g_array_append_val (array, list_value);
1786 while (g_ascii_isspace (*s))
1797 gst_structure_parse_list (gchar * s, gchar ** after, GValue * value, GType type)
1799 return gst_structure_parse_any_list (s, after, value, type, GST_TYPE_LIST,
1804 gst_structure_parse_array (gchar * s, gchar ** after, GValue * value,
1807 return gst_structure_parse_any_list (s, after, value, type,
1808 GST_TYPE_ARRAY, '<', '>');
1812 gst_structure_parse_simple_string (gchar * str, gchar ** end)
1816 while (GST_ASCII_IS_STRING (*s)) {
1826 gst_structure_parse_field (gchar * str,
1827 gchar ** after, GstStructureField * field)
1836 while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
1839 if (!gst_structure_parse_simple_string (s, &name_end))
1843 while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
1852 field->name = g_quark_from_string (name);
1855 if (!gst_structure_parse_value (s, &s, &field->value, G_TYPE_INVALID))
1863 gst_structure_parse_value (gchar * str,
1864 gchar ** after, GValue * value, GType default_type)
1873 GType type = default_type;
1876 while (g_ascii_isspace (*s))
1879 /* check if there's a (type_name) 'cast' */
1883 while (g_ascii_isspace (*s))
1886 if (!gst_structure_parse_simple_string (s, &type_end))
1889 while (g_ascii_isspace (*s))
1894 while (g_ascii_isspace (*s))
1899 type = gst_structure_gtype_from_abbr (type_name);
1902 if (G_UNLIKELY (type == G_TYPE_INVALID))
1906 while (g_ascii_isspace (*s))
1909 ret = gst_structure_parse_range (s, &s, value, type);
1910 } else if (*s == '{') {
1911 ret = gst_structure_parse_list (s, &s, value, type);
1912 } else if (*s == '<') {
1913 ret = gst_structure_parse_array (s, &s, value, type);
1916 if (G_UNLIKELY (!gst_structure_parse_string (s, &value_end, &s)))
1921 if (G_UNLIKELY (type == G_TYPE_INVALID)) {
1923 { G_TYPE_INT, G_TYPE_DOUBLE, GST_TYPE_FRACTION, G_TYPE_BOOLEAN,
1928 for (i = 0; i < G_N_ELEMENTS (try_types); i++) {
1929 g_value_init (value, try_types[i]);
1930 ret = gst_value_deserialize (value, value_s);
1933 g_value_unset (value);
1936 g_value_init (value, type);
1938 ret = gst_value_deserialize (value, value_s);
1939 if (G_UNLIKELY (!ret))
1940 g_value_unset (value);
1951 * gst_structure_from_string:
1952 * @string: a string representation of a #GstStructure.
1953 * @end: pointer to store the end of the string in.
1955 * Creates a #GstStructure from a string representation.
1956 * If end is not NULL, a pointer to the place inside the given string
1957 * where parsing ended will be returned.
1959 * Returns: a new #GstStructure or NULL when the string could not
1960 * be parsed. Free with gst_structure_free() after use.
1963 gst_structure_from_string (const gchar * string, gchar ** end)
1970 GstStructure *structure = NULL;
1971 GstStructureField field = { 0 };
1973 g_return_val_if_fail (string != NULL, NULL);
1975 copy = g_strdup (string);
1978 /* skip spaces (FIXME: _isspace treats tabs and newlines as space!) */
1979 while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
1980 && g_ascii_isspace (r[1]))))
1984 if (!gst_structure_parse_string (r, &w, &r)) {
1985 GST_WARNING ("Failed to parse structure string");
1991 structure = gst_structure_empty_new (name);
1994 if (G_UNLIKELY (structure == NULL))
1998 while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
1999 && g_ascii_isspace (r[1]))))
2002 /* end of structure, get the next char and finish */
2007 /* accept \0 as end delimiter */
2011 GST_WARNING ("Failed to find delimiter, r=%s", r);
2015 while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
2016 && g_ascii_isspace (r[1]))))
2019 memset (&field, 0, sizeof (field));
2020 if (!gst_structure_parse_field (r, &r, &field))
2022 gst_structure_set_field (structure, &field);
2026 *end = (char *) string + (r - copy);
2028 g_warning ("gst_structure_from_string did not consume whole string,"
2029 " but caller did not provide end pointer (\"%s\")", string);
2036 gst_structure_free (structure);
2042 gst_structure_transform_to_string (const GValue * src_value,
2043 GValue * dest_value)
2045 g_return_if_fail (src_value != NULL);
2046 g_return_if_fail (dest_value != NULL);
2048 dest_value->data[0].v_pointer =
2049 gst_structure_to_string (src_value->data[0].v_pointer);
2052 static GstStructure *
2053 gst_structure_copy_conditional (const GstStructure * structure)
2056 return gst_structure_copy (structure);
2060 /* fixate utility functions */
2063 * gst_structure_fixate_field_nearest_int:
2064 * @structure: a #GstStructure
2065 * @field_name: a field in @structure
2066 * @target: the target value of the fixation
2068 * Fixates a #GstStructure by changing the given field to the nearest
2069 * integer to @target that is a subset of the existing field.
2071 * Returns: TRUE if the structure could be fixated
2074 gst_structure_fixate_field_nearest_int (GstStructure * structure,
2075 const char *field_name, int target)
2077 const GValue *value;
2079 g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2080 g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2082 value = gst_structure_get_value (structure, field_name);
2084 if (G_VALUE_TYPE (value) == G_TYPE_INT) {
2087 } else if (G_VALUE_TYPE (value) == GST_TYPE_INT_RANGE) {
2090 x = gst_value_get_int_range_min (value);
2093 x = gst_value_get_int_range_max (value);
2096 gst_structure_set (structure, field_name, G_TYPE_INT, target, NULL);
2098 } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2099 const GValue *list_value;
2102 int best_index = -1;
2104 n = gst_value_list_get_size (value);
2105 for (i = 0; i < n; i++) {
2106 list_value = gst_value_list_get_value (value, i);
2107 if (G_VALUE_TYPE (list_value) == G_TYPE_INT) {
2108 int x = g_value_get_int (list_value);
2110 if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
2116 if (best_index != -1) {
2117 gst_structure_set (structure, field_name, G_TYPE_INT, best, NULL);
2127 * gst_structure_fixate_field_nearest_double:
2128 * @structure: a #GstStructure
2129 * @field_name: a field in @structure
2130 * @target: the target value of the fixation
2132 * Fixates a #GstStructure by changing the given field to the nearest
2133 * double to @target that is a subset of the existing field.
2135 * Returns: TRUE if the structure could be fixated
2138 gst_structure_fixate_field_nearest_double (GstStructure * structure,
2139 const char *field_name, double target)
2141 const GValue *value;
2143 g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2144 g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2146 value = gst_structure_get_value (structure, field_name);
2148 if (G_VALUE_TYPE (value) == G_TYPE_DOUBLE) {
2151 } else if (G_VALUE_TYPE (value) == GST_TYPE_DOUBLE_RANGE) {
2154 x = gst_value_get_double_range_min (value);
2157 x = gst_value_get_double_range_max (value);
2160 gst_structure_set (structure, field_name, G_TYPE_DOUBLE, target, NULL);
2162 } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2163 const GValue *list_value;
2166 int best_index = -1;
2168 n = gst_value_list_get_size (value);
2169 for (i = 0; i < n; i++) {
2170 list_value = gst_value_list_get_value (value, i);
2171 if (G_VALUE_TYPE (list_value) == G_TYPE_DOUBLE) {
2172 double x = g_value_get_double (list_value);
2174 if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
2180 if (best_index != -1) {
2181 gst_structure_set (structure, field_name, G_TYPE_DOUBLE, best, NULL);
2192 * gst_structure_fixate_field_boolean:
2193 * @structure: a #GstStructure
2194 * @field_name: a field in @structure
2195 * @target: the target value of the fixation
2197 * Fixates a #GstStructure by changing the given @field_name field to the given
2198 * @target boolean if that field is not fixed yet.
2200 * Returns: TRUE if the structure could be fixated
2203 gst_structure_fixate_field_boolean (GstStructure * structure,
2204 const char *field_name, gboolean target)
2206 const GValue *value;
2208 g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2209 g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2211 value = gst_structure_get_value (structure, field_name);
2213 if (G_VALUE_TYPE (value) == G_TYPE_BOOLEAN) {
2216 } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2217 const GValue *list_value;
2220 int best_index = -1;
2222 n = gst_value_list_get_size (value);
2223 for (i = 0; i < n; i++) {
2224 list_value = gst_value_list_get_value (value, i);
2225 if (G_VALUE_TYPE (list_value) == G_TYPE_BOOLEAN) {
2226 gboolean x = g_value_get_boolean (list_value);
2228 if (best_index == -1 || x == target) {
2234 if (best_index != -1) {
2235 gst_structure_set (structure, field_name, G_TYPE_BOOLEAN, best, NULL);
2245 * gst_structure_fixate_field_nearest_fraction:
2246 * @structure: a #GstStructure
2247 * @field_name: a field in @structure
2248 * @target_numerator: The numerator of the target value of the fixation
2249 * @target_denominator: The denominator of the target value of the fixation
2251 * Fixates a #GstStructure by changing the given field to the nearest
2252 * fraction to @target_numerator/@target_denominator that is a subset
2253 * of the existing field.
2255 * Returns: TRUE if the structure could be fixated
2258 gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
2259 const char *field_name, const gint target_numerator,
2260 const gint target_denominator)
2262 const GValue *value;
2264 g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2265 g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2267 value = gst_structure_get_value (structure, field_name);
2269 if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION) {
2272 } else if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION_RANGE) {
2273 const GValue *x, *new_value;
2274 GValue target = { 0 };
2275 g_value_init (&target, GST_TYPE_FRACTION);
2276 gst_value_set_fraction (&target, target_numerator, target_denominator);
2278 new_value = ⌖
2279 x = gst_value_get_fraction_range_min (value);
2280 if (gst_value_compare (&target, x) == GST_VALUE_LESS_THAN)
2282 x = gst_value_get_fraction_range_max (value);
2283 if (gst_value_compare (&target, x) == GST_VALUE_GREATER_THAN)
2286 gst_structure_set_value (structure, field_name, new_value);
2287 g_value_unset (&target);
2289 } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2290 const GValue *list_value;
2292 const GValue *best = NULL;
2295 gdouble best_diff = G_MAXDOUBLE;
2297 target = (gdouble) target_numerator / (gdouble) target_denominator;
2299 GST_DEBUG ("target %g, best %g", target, best_diff);
2303 n = gst_value_list_get_size (value);
2304 for (i = 0; i < n; i++) {
2305 list_value = gst_value_list_get_value (value, i);
2306 if (G_VALUE_TYPE (list_value) == GST_TYPE_FRACTION) {
2308 gdouble list_double;
2310 num = gst_value_get_fraction_numerator (list_value);
2311 denom = gst_value_get_fraction_denominator (list_value);
2313 list_double = ((gdouble) num / (gdouble) denom);
2314 cur_diff = target - list_double;
2316 GST_DEBUG ("curr diff %g, list %g", cur_diff, list_double);
2319 cur_diff = -cur_diff;
2321 if (!best || cur_diff < best_diff) {
2322 GST_DEBUG ("new best %g", list_double);
2324 best_diff = cur_diff;
2329 gst_structure_set_value (structure, field_name, best);