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