gst/gststructure.c

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