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     type = va_arg (varargs, GType);
 669
 670     G_VALUE_COLLECT_INIT (&field.value, type, varargs, 0, &err);
 671     if (G_UNLIKELY (err)) {
 672       g_critical ("%s", err);
 673       return;
 674     }
 675     gst_structure_set_field (structure, &field);
 676
 677     fieldname = va_arg (varargs, GQuark);
 678   }
 679 }
 680
 681 /**
 682  * gst_structure_id_set:
 683  * @structure: a #GstStructure
 684  * @fieldname: the GQuark for the name of the field to set
 685  * @...: variable arguments
 686  *
 687  * Identical to gst_structure_set, except that field names are
 688  * passed using the GQuark for the field name. This allows more efficient
 689  * setting of the structure if the caller already knows the associated
 690  * quark values.
 691  * The last variable argument must be %NULL.
 692  */
 693 void
 694 gst_structure_id_set (GstStructure * structure, GQuark field, ...)
 695 {
 696   va_list varargs;
 697
 698   g_return_if_fail (structure != NULL);
 699
 700   va_start (varargs, field);
 701   gst_structure_id_set_valist_internal (structure, field, varargs);
 702   va_end (varargs);
 703 }
 704
 705 /**
 706  * gst_structure_id_set_valist:
 707  * @structure: a #GstStructure
 708  * @fieldname: the name of the field to set
 709  * @varargs: variable arguments
 710  *
 711  * va_list form of gst_structure_id_set().
 712  */
 713 void
 714 gst_structure_id_set_valist (GstStructure * structure,
 715     GQuark fieldname, va_list varargs)
 716 {
 717   g_return_if_fail (structure != NULL);
 718   g_return_if_fail (IS_MUTABLE (structure));
 719
 720   gst_structure_id_set_valist_internal (structure, fieldname, varargs);
 721 }
 722
 723 /**
 724  * gst_structure_new_id:
 725  * @name_quark: name of new structure
 726  * @field_quark: the GQuark for the name of the field to set
 727  * @...: variable arguments
 728  *
 729  * Creates a new #GstStructure with the given name as a GQuark, followed by
 730  * fieldname quark, GType, argument(s) "triplets" in the same format as
 731  * gst_structure_id_set(). Basically a convenience wrapper around
 732  * gst_structure_new_id_empty() and gst_structure_id_set().
 733  *
 734  * The last variable argument must be %NULL (or 0).
 735  *
 736  * Free-function: gst_structure_free
 737  *
 738  * Returns: (transfer full): a new #GstStructure
 739  */
 740 GstStructure *
 741 gst_structure_new_id (GQuark name_quark, GQuark field_quark, ...)
 742 {
 743   GstStructure *s;
 744   va_list varargs;
 745
 746   g_return_val_if_fail (name_quark != 0, NULL);
 747   g_return_val_if_fail (field_quark != 0, NULL);
 748
 749   s = gst_structure_new_id_empty (name_quark);
 750
 751   va_start (varargs, field_quark);
 752   gst_structure_id_set_valist_internal (s, field_quark, varargs);
 753   va_end (varargs);
 754
 755   return s;
 756 }
 757
 758 #if GST_VERSION_NANO == 1
 759 #define GIT_G_WARNING g_warning
 760 #else
 761 #define GIT_G_WARNING GST_WARNING
 762 #endif
 763
 764 /* If the structure currently contains a field with the same name, it is
 765  * replaced with the provided field. Otherwise, the field is added to the
 766  * structure. The field's value is not deeply copied.
 767  */
 768 static void
 769 gst_structure_set_field (GstStructure * structure, GstStructureField * field)
 770 {
 771   GstStructureField *f;
 772   GType field_value_type;
 773   guint i, len;
 774
 775   len = GST_STRUCTURE_FIELDS (structure)->len;
 776
 777   field_value_type = G_VALUE_TYPE (&field->value);
 778   if (field_value_type == G_TYPE_STRING) {
 779     const gchar *s;
 780
 781     s = g_value_get_string (&field->value);
 782     /* only check for NULL strings in taglists, as they are allowed in message
 783      * structs, e.g. error message debug strings */
 784     if (G_UNLIKELY (IS_TAGLIST (structure) && (s == NULL || *s == '\0'))) {
 785       if (s == NULL) {
 786         GIT_G_WARNING ("Trying to set NULL string on field '%s' on taglist. "
 787             "Please file a bug.", g_quark_to_string (field->name));
 788         g_value_unset (&field->value);
 789         return;
 790       } else {
 791         /* empty strings never make sense */
 792         GIT_G_WARNING ("Trying to set empty string on taglist field '%s'. "
 793             "Please file a bug.", g_quark_to_string (field->name));
 794         g_value_unset (&field->value);
 795         return;
 796       }
 797     } else if (G_UNLIKELY (s != NULL && !g_utf8_validate (s, -1, NULL))) {
 798       g_warning ("Trying to set string on %s field '%s', but string is not "
 799           "valid UTF-8. Please file a bug.",
 800           IS_TAGLIST (structure) ? "taglist" : "structure",
 801           g_quark_to_string (field->name));
 802       g_value_unset (&field->value);
 803       return;
 804     }
 805   } else if (G_UNLIKELY (field_value_type == G_TYPE_DATE)) {
 806     const GDate *d;
 807
 808     d = g_value_get_boxed (&field->value);
 809     /* only check for NULL GDates in taglists, as they might make sense
 810      * in other, generic structs */
 811     if (G_UNLIKELY ((IS_TAGLIST (structure) && d == NULL))) {
 812       GIT_G_WARNING ("Trying to set NULL GDate on field '%s' on taglist. "
 813           "Please file a bug.", g_quark_to_string (field->name));
 814       g_value_unset (&field->value);
 815       return;
 816     } else if (G_UNLIKELY (d != NULL && !g_date_valid (d))) {
 817       g_warning
 818           ("Trying to set invalid GDate on %s field '%s'. Please file a bug.",
 819           IS_TAGLIST (structure) ? "taglist" : "structure",
 820           g_quark_to_string (field->name));
 821       g_value_unset (&field->value);
 822       return;
 823     }
 824   }
 825
 826   for (i = 0; i < len; i++) {
 827     f = GST_STRUCTURE_FIELD (structure, i);
 828
 829     if (G_UNLIKELY (f->name == field->name)) {
 830       g_value_unset (&f->value);
 831       memcpy (f, field, sizeof (GstStructureField));
 832       return;
 833     }
 834   }
 835
 836   g_array_append_val (GST_STRUCTURE_FIELDS (structure), *field);
 837 }
 838
 839 /* If there is no field with the given ID, NULL is returned.
 840  */
 841 static GstStructureField *
 842 gst_structure_id_get_field (const GstStructure * structure, GQuark field_id)
 843 {
 844   GstStructureField *field;
 845   guint i, len;
 846
 847   len = GST_STRUCTURE_FIELDS (structure)->len;
 848
 849   for (i = 0; i < len; i++) {
 850     field = GST_STRUCTURE_FIELD (structure, i);
 851
 852     if (G_UNLIKELY (field->name == field_id))
 853       return field;
 854   }
 855
 856   return NULL;
 857 }
 858
 859 /* If there is no field with the given ID, NULL is returned.
 860  */
 861 static GstStructureField *
 862 gst_structure_get_field (const GstStructure * structure,
 863     const gchar * fieldname)
 864 {
 865   g_return_val_if_fail (structure != NULL, NULL);
 866   g_return_val_if_fail (fieldname != NULL, NULL);
 867
 868   return gst_structure_id_get_field (structure,
 869       g_quark_from_string (fieldname));
 870 }
 871
 872 /**
 873  * gst_structure_get_value:
 874  * @structure: a #GstStructure
 875  * @fieldname: the name of the field to get
 876  *
 877  * Get the value of the field with name @fieldname.
 878  *
 879  * Returns: the #GValue corresponding to the field with the given name.
 880  */
 881 const GValue *
 882 gst_structure_get_value (const GstStructure * structure,
 883     const gchar * fieldname)
 884 {
 885   GstStructureField *field;
 886
 887   g_return_val_if_fail (structure != NULL, NULL);
 888   g_return_val_if_fail (fieldname != NULL, NULL);
 889
 890   field = gst_structure_get_field (structure, fieldname);
 891   if (field == NULL)
 892     return NULL;
 893
 894   return &field->value;
 895 }
 896
 897 /**
 898  * gst_structure_id_get_value:
 899  * @structure: a #GstStructure
 900  * @field: the #GQuark of the field to get
 901  *
 902  * Get the value of the field with GQuark @field.
 903  *
 904  * Returns: the #GValue corresponding to the field with the given name
 905  *          identifier.
 906  */
 907 const GValue *
 908 gst_structure_id_get_value (const GstStructure * structure, GQuark field)
 909 {
 910   GstStructureField *gsfield;
 911
 912   g_return_val_if_fail (structure != NULL, NULL);
 913
 914   gsfield = gst_structure_id_get_field (structure, field);
 915   if (gsfield == NULL)
 916     return NULL;
 917
 918   return &gsfield->value;
 919 }
 920
 921 /**
 922  * gst_structure_remove_field:
 923  * @structure: a #GstStructure
 924  * @fieldname: the name of the field to remove
 925  *
 926  * Removes the field with the given name.  If the field with the given
 927  * name does not exist, the structure is unchanged.
 928  */
 929 void
 930 gst_structure_remove_field (GstStructure * structure, const gchar * fieldname)
 931 {
 932   GstStructureField *field;
 933   GQuark id;
 934   guint i, len;
 935
 936   g_return_if_fail (structure != NULL);
 937   g_return_if_fail (fieldname != NULL);
 938   g_return_if_fail (IS_MUTABLE (structure));
 939
 940   id = g_quark_from_string (fieldname);
 941   len = GST_STRUCTURE_FIELDS (structure)->len;
 942
 943   for (i = 0; i < len; i++) {
 944     field = GST_STRUCTURE_FIELD (structure, i);
 945
 946     if (field->name == id) {
 947       if (G_IS_VALUE (&field->value)) {
 948         g_value_unset (&field->value);
 949       }
 950       GST_STRUCTURE_FIELDS (structure) =
 951           g_array_remove_index (GST_STRUCTURE_FIELDS (structure), i);
 952       return;
 953     }
 954   }
 955 }
 956
 957 /**
 958  * gst_structure_remove_fields:
 959  * @structure: a #GstStructure
 960  * @fieldname: the name of the field to remove
 961  * @...: %NULL-terminated list of more fieldnames to remove
 962  *
 963  * Removes the fields with the given names. If a field does not exist, the
 964  * argument is ignored.
 965  */
 966 void
 967 gst_structure_remove_fields (GstStructure * structure,
 968     const gchar * fieldname, ...)
 969 {
 970   va_list varargs;
 971
 972   g_return_if_fail (structure != NULL);
 973   g_return_if_fail (fieldname != NULL);
 974   /* mutability checked in remove_field */
 975
 976   va_start (varargs, fieldname);
 977   gst_structure_remove_fields_valist (structure, fieldname, varargs);
 978   va_end (varargs);
 979 }
 980
 981 /**
 982  * gst_structure_remove_fields_valist:
 983  * @structure: a #GstStructure
 984  * @fieldname: the name of the field to remove
 985  * @varargs: %NULL-terminated list of more fieldnames to remove
 986  *
 987  * va_list form of gst_structure_remove_fields().
 988  */
 989 void
 990 gst_structure_remove_fields_valist (GstStructure * structure,
 991     const gchar * fieldname, va_list varargs)
 992 {
 993   gchar *field = (gchar *) fieldname;
 994
 995   g_return_if_fail (structure != NULL);
 996   g_return_if_fail (fieldname != NULL);
 997   /* mutability checked in remove_field */
 998
 999   while (field) {
1000     gst_structure_remove_field (structure, field);
1001     field = va_arg (varargs, char *);
1002   }
1003 }
1004
1005 /**
1006  * gst_structure_remove_all_fields:
1007  * @structure: a #GstStructure
1008  *
1009  * Removes all fields in a GstStructure.
1010  */
1011 void
1012 gst_structure_remove_all_fields (GstStructure * structure)
1013 {
1014   GstStructureField *field;
1015   int i;
1016
1017   g_return_if_fail (structure != NULL);
1018   g_return_if_fail (IS_MUTABLE (structure));
1019
1020   for (i = GST_STRUCTURE_FIELDS (structure)->len - 1; i >= 0; i--) {
1021     field = GST_STRUCTURE_FIELD (structure, i);
1022
1023     if (G_IS_VALUE (&field->value)) {
1024       g_value_unset (&field->value);
1025     }
1026     GST_STRUCTURE_FIELDS (structure) =
1027         g_array_remove_index (GST_STRUCTURE_FIELDS (structure), i);
1028   }
1029 }
1030
1031 /**
1032  * gst_structure_get_field_type:
1033  * @structure: a #GstStructure
1034  * @fieldname: the name of the field
1035  *
1036  * Finds the field with the given name, and returns the type of the
1037  * value it contains.  If the field is not found, G_TYPE_INVALID is
1038  * returned.
1039  *
1040  * Returns: the #GValue of the field
1041  */
1042 GType
1043 gst_structure_get_field_type (const GstStructure * structure,
1044     const gchar * fieldname)
1045 {
1046   GstStructureField *field;
1047
1048   g_return_val_if_fail (structure != NULL, G_TYPE_INVALID);
1049   g_return_val_if_fail (fieldname != NULL, G_TYPE_INVALID);
1050
1051   field = gst_structure_get_field (structure, fieldname);
1052   if (field == NULL)
1053     return G_TYPE_INVALID;
1054
1055   return G_VALUE_TYPE (&field->value);
1056 }
1057
1058 /**
1059  * gst_structure_n_fields:
1060  * @structure: a #GstStructure
1061  *
1062  * Get the number of fields in the structure.
1063  *
1064  * Returns: the number of fields in the structure
1065  */
1066 gint
1067 gst_structure_n_fields (const GstStructure * structure)
1068 {
1069   g_return_val_if_fail (structure != NULL, 0);
1070
1071   return GST_STRUCTURE_FIELDS (structure)->len;
1072 }
1073
1074 /**
1075  * gst_structure_nth_field_name:
1076  * @structure: a #GstStructure
1077  * @index: the index to get the name of
1078  *
1079  * Get the name of the given field number, counting from 0 onwards.
1080  *
1081  * Returns: the name of the given field number
1082  */
1083 const gchar *
1084 gst_structure_nth_field_name (const GstStructure * structure, guint index)
1085 {
1086   GstStructureField *field;
1087
1088   g_return_val_if_fail (structure != NULL, NULL);
1089   g_return_val_if_fail (index < GST_STRUCTURE_FIELDS (structure)->len, NULL);
1090
1091   field = GST_STRUCTURE_FIELD (structure, index);
1092
1093   return g_quark_to_string (field->name);
1094 }
1095
1096 /**
1097  * gst_structure_foreach:
1098  * @structure: a #GstStructure
1099  * @func: (scope call): a function to call for each field
1100  * @user_data: (closure): private data
1101  *
1102  * Calls the provided function once for each field in the #GstStructure. The
1103  * function must not modify the fields. Also see gst_structure_map_in_place()
1104  * and gst_structure_filter_and_map_in_place().
1105  *
1106  * Returns: %TRUE if the supplied function returns %TRUE For each of the fields,
1107  * %FALSE otherwise.
1108  */
1109 gboolean
1110 gst_structure_foreach (const GstStructure * structure,
1111     GstStructureForeachFunc func, gpointer user_data)
1112 {
1113   guint i, len;
1114   GstStructureField *field;
1115   gboolean ret;
1116
1117   g_return_val_if_fail (structure != NULL, FALSE);
1118   g_return_val_if_fail (func != NULL, FALSE);
1119
1120   len = GST_STRUCTURE_FIELDS (structure)->len;
1121
1122   for (i = 0; i < len; i++) {
1123     field = GST_STRUCTURE_FIELD (structure, i);
1124
1125     ret = func (field->name, &field->value, user_data);
1126     if (G_UNLIKELY (!ret))
1127       return FALSE;
1128   }
1129
1130   return TRUE;
1131 }
1132
1133 /**
1134  * gst_structure_map_in_place:
1135  * @structure: a #GstStructure
1136  * @func: (scope call): a function to call for each field
1137  * @user_data: (closure): private data
1138  *
1139  * Calls the provided function once for each field in the #GstStructure. In
1140  * contrast to gst_structure_foreach(), the function may modify but not delete the
1141  * fields. The structure must be mutable.
1142  *
1143  * Returns: %TRUE if the supplied function returns %TRUE For each of the fields,
1144  * %FALSE otherwise.
1145  */
1146 gboolean
1147 gst_structure_map_in_place (GstStructure * structure,
1148     GstStructureMapFunc func, gpointer user_data)
1149 {
1150   guint i, len;
1151   GstStructureField *field;
1152   gboolean ret;
1153
1154   g_return_val_if_fail (structure != NULL, FALSE);
1155   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1156   g_return_val_if_fail (func != NULL, FALSE);
1157   len = GST_STRUCTURE_FIELDS (structure)->len;
1158
1159   for (i = 0; i < len; i++) {
1160     field = GST_STRUCTURE_FIELD (structure, i);
1161
1162     ret = func (field->name, &field->value, user_data);
1163     if (!ret)
1164       return FALSE;
1165   }
1166
1167   return TRUE;
1168 }
1169
1170 /**
1171  * gst_structure_filter_and_map_in_place:
1172  * @structure: a #GstStructure
1173  * @func: (scope call): a function to call for each field
1174  * @user_data: (closure): private data
1175  *
1176  * Calls the provided function once for each field in the #GstStructure. In
1177  * contrast to gst_structure_foreach(), the function may modify the fields.
1178  * In contrast to gst_structure_map_in_place(), the field is removed from
1179  * the structure if %FALSE is returned from the function.
1180  * The structure must be mutable.
1181  *
1182  * Since: 1.6
1183  */
1184 void
1185 gst_structure_filter_and_map_in_place (GstStructure * structure,
1186     GstStructureFilterMapFunc func, gpointer user_data)
1187 {
1188   guint i, len;
1189   GstStructureField *field;
1190   gboolean ret;
1191
1192   g_return_if_fail (structure != NULL);
1193   g_return_if_fail (IS_MUTABLE (structure));
1194   g_return_if_fail (func != NULL);
1195   len = GST_STRUCTURE_FIELDS (structure)->len;
1196
1197   for (i = 0; i < len;) {
1198     field = GST_STRUCTURE_FIELD (structure, i);
1199
1200     ret = func (field->name, &field->value, user_data);
1201
1202     if (!ret) {
1203       if (G_IS_VALUE (&field->value)) {
1204         g_value_unset (&field->value);
1205       }
1206       GST_STRUCTURE_FIELDS (structure) =
1207           g_array_remove_index (GST_STRUCTURE_FIELDS (structure), i);
1208       len = GST_STRUCTURE_FIELDS (structure)->len;
1209     } else {
1210       i++;
1211     }
1212   }
1213 }
1214
1215 /**
1216  * gst_structure_id_has_field:
1217  * @structure: a #GstStructure
1218  * @field: #GQuark of the field name
1219  *
1220  * Check if @structure contains a field named @field.
1221  *
1222  * Returns: %TRUE if the structure contains a field with the given name
1223  */
1224 gboolean
1225 gst_structure_id_has_field (const GstStructure * structure, GQuark field)
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
1234   return (f != NULL);
1235 }
1236
1237 /**
1238  * gst_structure_has_field:
1239  * @structure: a #GstStructure
1240  * @fieldname: the name of a field
1241  *
1242  * Check if @structure contains a field named @fieldname.
1243  *
1244  * Returns: %TRUE if the structure contains a field with the given name
1245  */
1246 gboolean
1247 gst_structure_has_field (const GstStructure * structure,
1248     const gchar * fieldname)
1249 {
1250   g_return_val_if_fail (structure != NULL, FALSE);
1251   g_return_val_if_fail (fieldname != NULL, FALSE);
1252
1253   return gst_structure_id_has_field (structure,
1254       g_quark_from_string (fieldname));
1255 }
1256
1257 /**
1258  * gst_structure_id_has_field_typed:
1259  * @structure: a #GstStructure
1260  * @field: #GQuark of the field name
1261  * @type: the type of a value
1262  *
1263  * Check if @structure contains a field named @field and with GType @type.
1264  *
1265  * Returns: %TRUE if the structure contains a field with the given name and type
1266  */
1267 gboolean
1268 gst_structure_id_has_field_typed (const GstStructure * structure,
1269     GQuark field, GType type)
1270 {
1271   GstStructureField *f;
1272
1273   g_return_val_if_fail (structure != NULL, FALSE);
1274   g_return_val_if_fail (field != 0, FALSE);
1275
1276   f = gst_structure_id_get_field (structure, field);
1277   if (f == NULL)
1278     return FALSE;
1279
1280   return (G_VALUE_TYPE (&f->value) == type);
1281 }
1282
1283 /**
1284  * gst_structure_has_field_typed:
1285  * @structure: a #GstStructure
1286  * @fieldname: the name of a field
1287  * @type: the type of a value
1288  *
1289  * Check if @structure contains a field named @fieldname and with GType @type.
1290  *
1291  * Returns: %TRUE if the structure contains a field with the given name and type
1292  */
1293 gboolean
1294 gst_structure_has_field_typed (const GstStructure * structure,
1295     const gchar * fieldname, GType type)
1296 {
1297   g_return_val_if_fail (structure != NULL, FALSE);
1298   g_return_val_if_fail (fieldname != NULL, FALSE);
1299
1300   return gst_structure_id_has_field_typed (structure,
1301       g_quark_from_string (fieldname), type);
1302 }
1303
1304 /* utility functions */
1305
1306 /**
1307  * gst_structure_get_boolean:
1308  * @structure: a #GstStructure
1309  * @fieldname: the name of a field
1310  * @value: (out): a pointer to a #gboolean to set
1311  *
1312  * Sets the boolean pointed to by @value corresponding to the value of the
1313  * given field.  Caller is responsible for making sure the field exists
1314  * and has the correct type.
1315  *
1316  * Returns: %TRUE if the value could be set correctly. If there was no field
1317  * with @fieldname or the existing field did not contain a boolean, this
1318  * function returns %FALSE.
1319  */
1320 gboolean
1321 gst_structure_get_boolean (const GstStructure * structure,
1322     const gchar * fieldname, gboolean * value)
1323 {
1324   GstStructureField *field;
1325
1326   g_return_val_if_fail (structure != NULL, FALSE);
1327   g_return_val_if_fail (fieldname != NULL, FALSE);
1328
1329   field = gst_structure_get_field (structure, fieldname);
1330
1331   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_BOOLEAN)
1332     return FALSE;
1333
1334   *value = gst_g_value_get_boolean_unchecked (&field->value);
1335
1336   return TRUE;
1337 }
1338
1339 /**
1340  * gst_structure_get_int:
1341  * @structure: a #GstStructure
1342  * @fieldname: the name of a field
1343  * @value: (out): a pointer to an int to set
1344  *
1345  * Sets the int pointed to by @value corresponding to the value of the
1346  * given field.  Caller is responsible for making sure the field exists
1347  * and has the correct type.
1348  *
1349  * Returns: %TRUE if the value could be set correctly. If there was no field
1350  * with @fieldname or the existing field did not contain an int, this function
1351  * returns %FALSE.
1352  */
1353 gboolean
1354 gst_structure_get_int (const GstStructure * structure,
1355     const gchar * fieldname, gint * value)
1356 {
1357   GstStructureField *field;
1358
1359   g_return_val_if_fail (structure != NULL, FALSE);
1360   g_return_val_if_fail (fieldname != NULL, FALSE);
1361   g_return_val_if_fail (value != NULL, FALSE);
1362
1363   field = gst_structure_get_field (structure, fieldname);
1364
1365   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_INT)
1366     return FALSE;
1367
1368   *value = gst_g_value_get_int_unchecked (&field->value);
1369
1370   return TRUE;
1371 }
1372
1373 /**
1374  * gst_structure_get_uint:
1375  * @structure: a #GstStructure
1376  * @fieldname: the name of a field
1377  * @value: (out): a pointer to a uint to set
1378  *
1379  * Sets the uint pointed to by @value corresponding to the value of the
1380  * given field.  Caller is responsible for making sure the field exists
1381  * and has the correct type.
1382  *
1383  * Returns: %TRUE if the value could be set correctly. If there was no field
1384  * with @fieldname or the existing field did not contain a uint, this function
1385  * returns %FALSE.
1386  */
1387 gboolean
1388 gst_structure_get_uint (const GstStructure * structure,
1389     const gchar * fieldname, guint * value)
1390 {
1391   GstStructureField *field;
1392
1393   g_return_val_if_fail (structure != NULL, FALSE);
1394   g_return_val_if_fail (fieldname != NULL, FALSE);
1395   g_return_val_if_fail (value != NULL, FALSE);
1396
1397   field = gst_structure_get_field (structure, fieldname);
1398
1399   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_UINT)
1400     return FALSE;
1401
1402   *value = gst_g_value_get_uint_unchecked (&field->value);
1403
1404   return TRUE;
1405 }
1406
1407 /**
1408  * gst_structure_get_int64:
1409  * @structure: a #GstStructure
1410  * @fieldname: the name of a field
1411  * @value: (out): a pointer to a #gint64 to set
1412  *
1413  * Sets the #gint64 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 #gint64, this function
1419  * returns %FALSE.
1420  *
1421  * Since: 1.4
1422  */
1423 gboolean
1424 gst_structure_get_int64 (const GstStructure * structure,
1425     const gchar * fieldname, gint64 * 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 || G_VALUE_TYPE (&field->value) != G_TYPE_INT64)
1436     return FALSE;
1437
1438   *value = gst_g_value_get_int64_unchecked (&field->value);
1439
1440   return TRUE;
1441 }
1442
1443 /**
1444  * gst_structure_get_uint64:
1445  * @structure: a #GstStructure
1446  * @fieldname: the name of a field
1447  * @value: (out): a pointer to a #guint64 to set
1448  *
1449  * Sets the #guint64 pointed to by @value corresponding to the value of the
1450  * given field. Caller is responsible for making sure the field exists
1451  * and has the correct type.
1452  *
1453  * Returns: %TRUE if the value could be set correctly. If there was no field
1454  * with @fieldname or the existing field did not contain a #guint64, this function
1455  * returns %FALSE.
1456  *
1457  * Since: 1.4
1458  */
1459 gboolean
1460 gst_structure_get_uint64 (const GstStructure * structure,
1461     const gchar * fieldname, guint64 * value)
1462 {
1463   GstStructureField *field;
1464
1465   g_return_val_if_fail (structure != NULL, FALSE);
1466   g_return_val_if_fail (fieldname != NULL, FALSE);
1467   g_return_val_if_fail (value != NULL, FALSE);
1468
1469   field = gst_structure_get_field (structure, fieldname);
1470
1471   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_UINT64)
1472     return FALSE;
1473
1474   *value = gst_g_value_get_uint64_unchecked (&field->value);
1475
1476   return TRUE;
1477 }
1478
1479 /**
1480  * gst_structure_get_date:
1481  * @structure: a #GstStructure
1482  * @fieldname: the name of a field
1483  * @value: (out callee-allocates): a pointer to a #GDate to set
1484  *
1485  * Sets the date pointed to by @value corresponding to the date of the
1486  * given field.  Caller is responsible for making sure the field exists
1487  * and has the correct type.
1488  *
1489  * On success @value will point to a newly-allocated copy of the date which
1490  * should be freed with g_date_free() when no longer needed (note: this is
1491  * inconsistent with e.g. gst_structure_get_string() which doesn't return a
1492  * copy of the string).
1493  *
1494  * Returns: %TRUE if the value could be set correctly. If there was no field
1495  * with @fieldname or the existing field did not contain a data, this function
1496  * returns %FALSE.
1497  */
1498 gboolean
1499 gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
1500     GDate ** value)
1501 {
1502   GstStructureField *field;
1503
1504   g_return_val_if_fail (structure != NULL, FALSE);
1505   g_return_val_if_fail (fieldname != NULL, FALSE);
1506   g_return_val_if_fail (value != NULL, FALSE);
1507
1508   field = gst_structure_get_field (structure, fieldname);
1509
1510   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_DATE)
1511     return FALSE;
1512
1513   /* FIXME: 2.0 g_value_dup_boxed() -> g_value_get_boxed() */
1514   *value = g_value_dup_boxed (&field->value);
1515
1516   return TRUE;
1517 }
1518
1519 /**
1520  * gst_structure_get_date_time:
1521  * @structure: a #GstStructure
1522  * @fieldname: the name of a field
1523  * @value: (out callee-allocates): a pointer to a #GstDateTime to set
1524  *
1525  * Sets the datetime pointed to by @value corresponding to the datetime of the
1526  * given field. Caller is responsible for making sure the field exists
1527  * and has the correct type.
1528  *
1529  * On success @value will point to a reference of the datetime which
1530  * should be unreffed with gst_date_time_unref() when no longer needed
1531  * (note: this is inconsistent with e.g. gst_structure_get_string()
1532  * which doesn't return a copy of the string).
1533  *
1534  * Returns: %TRUE if the value could be set correctly. If there was no field
1535  * with @fieldname or the existing field did not contain a data, this function
1536  * returns %FALSE.
1537  */
1538 gboolean
1539 gst_structure_get_date_time (const GstStructure * structure,
1540     const gchar * fieldname, GstDateTime ** value)
1541 {
1542   GstStructureField *field;
1543
1544   g_return_val_if_fail (structure != NULL, FALSE);
1545   g_return_val_if_fail (fieldname != NULL, FALSE);
1546   g_return_val_if_fail (value != NULL, FALSE);
1547
1548   field = gst_structure_get_field (structure, fieldname);
1549
1550   if (field == NULL)
1551     return FALSE;
1552   if (!GST_VALUE_HOLDS_DATE_TIME (&field->value))
1553     return FALSE;
1554
1555   /* FIXME 2.0: g_value_dup_boxed() -> g_value_get_boxed() */
1556   *value = g_value_dup_boxed (&field->value);
1557
1558   return TRUE;
1559 }
1560
1561 /**
1562  * gst_structure_get_clock_time:
1563  * @structure: a #GstStructure
1564  * @fieldname: the name of a field
1565  * @value: (out): a pointer to a #GstClockTime to set
1566  *
1567  * Sets the clock time pointed to by @value corresponding to the clock time
1568  * of the given field.  Caller is responsible for making sure the field exists
1569  * and has the correct type.
1570  *
1571  * Returns: %TRUE if the value could be set correctly. If there was no field
1572  * with @fieldname or the existing field did not contain a #GstClockTime, this
1573  * function returns %FALSE.
1574  */
1575 gboolean
1576 gst_structure_get_clock_time (const GstStructure * structure,
1577     const gchar * fieldname, GstClockTime * value)
1578 {
1579   return gst_structure_get_uint64 (structure, fieldname, value);
1580 }
1581
1582 /**
1583  * gst_structure_get_double:
1584  * @structure: a #GstStructure
1585  * @fieldname: the name of a field
1586  * @value: (out): a pointer to a gdouble to set
1587  *
1588  * Sets the double pointed to by @value corresponding to the value of the
1589  * given field.  Caller is responsible for making sure the field exists
1590  * and has the correct type.
1591  *
1592  * Returns: %TRUE if the value could be set correctly. If there was no field
1593  * with @fieldname or the existing field did not contain a double, this
1594  * function returns %FALSE.
1595  */
1596 gboolean
1597 gst_structure_get_double (const GstStructure * structure,
1598     const gchar * fieldname, gdouble * value)
1599 {
1600   GstStructureField *field;
1601
1602   g_return_val_if_fail (structure != NULL, FALSE);
1603   g_return_val_if_fail (fieldname != NULL, FALSE);
1604   g_return_val_if_fail (value != NULL, FALSE);
1605
1606   field = gst_structure_get_field (structure, fieldname);
1607
1608   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_DOUBLE)
1609     return FALSE;
1610
1611   *value = gst_g_value_get_double_unchecked (&field->value);
1612
1613   return TRUE;
1614 }
1615
1616 /**
1617  * gst_structure_get_string:
1618  * @structure: a #GstStructure
1619  * @fieldname: the name of a field
1620  *
1621  * Finds the field corresponding to @fieldname, and returns the string
1622  * contained in the field's value.  Caller is responsible for making
1623  * sure the field exists and has the correct type.
1624  *
1625  * The string should not be modified, and remains valid until the next
1626  * call to a gst_structure_*() function with the given structure.
1627  *
1628  * Returns: (nullable): a pointer to the string or %NULL when the
1629  * field did not exist or did not contain a string.
1630  */
1631 const gchar *
1632 gst_structure_get_string (const GstStructure * structure,
1633     const gchar * fieldname)
1634 {
1635   GstStructureField *field;
1636
1637   g_return_val_if_fail (structure != NULL, NULL);
1638   g_return_val_if_fail (fieldname != NULL, NULL);
1639
1640   field = gst_structure_get_field (structure, fieldname);
1641
1642   if (field == NULL || G_VALUE_TYPE (&field->value) != G_TYPE_STRING)
1643     return NULL;
1644
1645   return gst_g_value_get_string_unchecked (&field->value);
1646 }
1647
1648 /**
1649  * gst_structure_get_enum:
1650  * @structure: a #GstStructure
1651  * @fieldname: the name of a field
1652  * @enumtype: the enum type of a field
1653  * @value: (out): a pointer to an int to set
1654  *
1655  * Sets the int pointed to by @value corresponding to the value of the
1656  * given field.  Caller is responsible for making sure the field exists,
1657  * has the correct type and that the enumtype is correct.
1658  *
1659  * Returns: %TRUE if the value could be set correctly. If there was no field
1660  * with @fieldname or the existing field did not contain an enum of the given
1661  * type, this function returns %FALSE.
1662  */
1663 gboolean
1664 gst_structure_get_enum (const GstStructure * structure,
1665     const gchar * fieldname, GType enumtype, gint * value)
1666 {
1667   GstStructureField *field;
1668
1669   g_return_val_if_fail (structure != NULL, FALSE);
1670   g_return_val_if_fail (fieldname != NULL, FALSE);
1671   g_return_val_if_fail (enumtype != G_TYPE_INVALID, FALSE);
1672   g_return_val_if_fail (value != NULL, FALSE);
1673
1674   field = gst_structure_get_field (structure, fieldname);
1675
1676   if (field == NULL)
1677     return FALSE;
1678   if (!G_TYPE_CHECK_VALUE_TYPE (&field->value, enumtype))
1679     return FALSE;
1680
1681   *value = g_value_get_enum (&field->value);
1682
1683   return TRUE;
1684 }
1685
1686 /**
1687  * gst_structure_get_fraction:
1688  * @structure: a #GstStructure
1689  * @fieldname: the name of a field
1690  * @value_numerator: (out): a pointer to an int to set
1691  * @value_denominator: (out): a pointer to an int to set
1692  *
1693  * Sets the integers pointed to by @value_numerator and @value_denominator
1694  * corresponding to the value of the given field.  Caller is responsible
1695  * for making sure the field exists and has the correct type.
1696  *
1697  * Returns: %TRUE if the values could be set correctly. If there was no field
1698  * with @fieldname or the existing field did not contain a GstFraction, this
1699  * function returns %FALSE.
1700  */
1701 gboolean
1702 gst_structure_get_fraction (const GstStructure * structure,
1703     const gchar * fieldname, gint * value_numerator, gint * value_denominator)
1704 {
1705   GstStructureField *field;
1706
1707   g_return_val_if_fail (structure != NULL, FALSE);
1708   g_return_val_if_fail (fieldname != NULL, FALSE);
1709   g_return_val_if_fail (value_numerator != NULL, FALSE);
1710   g_return_val_if_fail (value_denominator != NULL, FALSE);
1711
1712   field = gst_structure_get_field (structure, fieldname);
1713
1714   if (field == NULL || G_VALUE_TYPE (&field->value) != GST_TYPE_FRACTION)
1715     return FALSE;
1716
1717   *value_numerator = gst_value_get_fraction_numerator (&field->value);
1718   *value_denominator = gst_value_get_fraction_denominator (&field->value);
1719
1720   return TRUE;
1721 }
1722
1723 typedef struct _GstStructureAbbreviation
1724 {
1725   const gchar *type_name;
1726   GType type;
1727 }
1728 GstStructureAbbreviation;
1729
1730 /* return a copy of an array of GstStructureAbbreviation containing all the
1731  * known type_string, GType maps, including abbreviations for common types */
1732 static GstStructureAbbreviation *
1733 gst_structure_get_abbrs (gint * n_abbrs)
1734 {
1735   static GstStructureAbbreviation *abbrs = NULL;
1736   static volatile gsize num = 0;
1737
1738   if (g_once_init_enter (&num)) {
1739     /* dynamically generate the array */
1740     gsize _num;
1741     GstStructureAbbreviation dyn_abbrs[] = {
1742       {"int", G_TYPE_INT}
1743       ,
1744       {"i", G_TYPE_INT}
1745       ,
1746       {"uint", G_TYPE_UINT}
1747       ,
1748       {"u", G_TYPE_UINT}
1749       ,
1750       {"float", G_TYPE_FLOAT}
1751       ,
1752       {"f", G_TYPE_FLOAT}
1753       ,
1754       {"double", G_TYPE_DOUBLE}
1755       ,
1756       {"d", G_TYPE_DOUBLE}
1757       ,
1758       {"buffer", GST_TYPE_BUFFER}
1759       ,
1760       {"fraction", GST_TYPE_FRACTION}
1761       ,
1762       {"boolean", G_TYPE_BOOLEAN}
1763       ,
1764       {"bool", G_TYPE_BOOLEAN}
1765       ,
1766       {"b", G_TYPE_BOOLEAN}
1767       ,
1768       {"string", G_TYPE_STRING}
1769       ,
1770       {"str", G_TYPE_STRING}
1771       ,
1772       {"s", G_TYPE_STRING}
1773       ,
1774       {"structure", GST_TYPE_STRUCTURE}
1775       ,
1776       {"date", G_TYPE_DATE}
1777       ,
1778       {"datetime", GST_TYPE_DATE_TIME}
1779       ,
1780       {"bitmask", GST_TYPE_BITMASK}
1781       ,
1782       {"sample", GST_TYPE_SAMPLE}
1783       ,
1784       {"taglist", GST_TYPE_TAG_LIST}
1785     };
1786     _num = G_N_ELEMENTS (dyn_abbrs);
1787     /* permanently allocate and copy the array now */
1788     abbrs = g_new0 (GstStructureAbbreviation, _num);
1789     memcpy (abbrs, dyn_abbrs, sizeof (GstStructureAbbreviation) * _num);
1790     g_once_init_leave (&num, _num);
1791   }
1792   *n_abbrs = num;
1793
1794   return abbrs;
1795 }
1796
1797 /* given a type_name that could be a type abbreviation or a registered GType,
1798  * return a matching GType */
1799 static GType
1800 gst_structure_gtype_from_abbr (const char *type_name)
1801 {
1802   int i;
1803   GstStructureAbbreviation *abbrs;
1804   gint n_abbrs;
1805
1806   g_return_val_if_fail (type_name != NULL, G_TYPE_INVALID);
1807
1808   abbrs = gst_structure_get_abbrs (&n_abbrs);
1809
1810   for (i = 0; i < n_abbrs; i++) {
1811     if (strcmp (type_name, abbrs[i].type_name) == 0) {
1812       return abbrs[i].type;
1813     }
1814   }
1815
1816   /* this is the fallback */
1817   return g_type_from_name (type_name);
1818 }
1819
1820 static const char *
1821 gst_structure_to_abbr (GType type)
1822 {
1823   int i;
1824   GstStructureAbbreviation *abbrs;
1825   gint n_abbrs;
1826
1827   g_return_val_if_fail (type != G_TYPE_INVALID, NULL);
1828
1829   abbrs = gst_structure_get_abbrs (&n_abbrs);
1830
1831   for (i = 0; i < n_abbrs; i++) {
1832     if (type == abbrs[i].type) {
1833       return abbrs[i].type_name;
1834     }
1835   }
1836
1837   return g_type_name (type);
1838 }
1839
1840 static GType
1841 gst_structure_value_get_generic_type (GValue * val)
1842 {
1843   if (G_VALUE_TYPE (val) == GST_TYPE_LIST
1844       || G_VALUE_TYPE (val) == GST_TYPE_ARRAY) {
1845     GArray *array = g_value_peek_pointer (val);
1846
1847     if (array->len > 0) {
1848       GValue *value = &g_array_index (array, GValue, 0);
1849
1850       return gst_structure_value_get_generic_type (value);
1851     } else {
1852       return G_TYPE_INT;
1853     }
1854   } else if (G_VALUE_TYPE (val) == GST_TYPE_INT_RANGE) {
1855     return G_TYPE_INT;
1856   } else if (G_VALUE_TYPE (val) == GST_TYPE_INT64_RANGE) {
1857     return G_TYPE_INT64;
1858   } else if (G_VALUE_TYPE (val) == GST_TYPE_DOUBLE_RANGE) {
1859     return G_TYPE_DOUBLE;
1860   } else if (G_VALUE_TYPE (val) == GST_TYPE_FRACTION_RANGE) {
1861     return GST_TYPE_FRACTION;
1862   }
1863   return G_VALUE_TYPE (val);
1864 }
1865
1866 gboolean
1867 priv_gst_structure_append_to_gstring (const GstStructure * structure,
1868     GString * s)
1869 {
1870   GstStructureField *field;
1871   guint i, len;
1872
1873   g_return_val_if_fail (s != NULL, FALSE);
1874
1875   len = GST_STRUCTURE_FIELDS (structure)->len;
1876   for (i = 0; i < len; i++) {
1877     char *t;
1878     GType type;
1879
1880     field = GST_STRUCTURE_FIELD (structure, i);
1881
1882     t = gst_value_serialize (&field->value);
1883     type = gst_structure_value_get_generic_type (&field->value);
1884
1885     g_string_append_len (s, ", ", 2);
1886     /* FIXME: do we need to escape fieldnames? */
1887     g_string_append (s, g_quark_to_string (field->name));
1888     g_string_append_len (s, "=(", 2);
1889     g_string_append (s, gst_structure_to_abbr (type));
1890     g_string_append_c (s, ')');
1891     g_string_append (s, t == NULL ? "NULL" : t);
1892     g_free (t);
1893   }
1894
1895   g_string_append_c (s, ';');
1896   return TRUE;
1897 }
1898
1899 /**
1900  * gst_structure_to_string:
1901  * @structure: a #GstStructure
1902  *
1903  * Converts @structure to a human-readable string representation.
1904  *
1905  * For debugging purposes its easier to do something like this:
1906  * |[
1907  * GST_LOG ("structure is %" GST_PTR_FORMAT, structure);
1908  * ]|
1909  * This prints the structure in human readable form.
1910  *
1911  * The current implementation of serialization will lead to unexpected results
1912  * when there are nested #GstCaps / #GstStructure deeper than one level.
1913  *
1914  * Free-function: g_free
1915  *
1916  * Returns: (transfer full): a pointer to string allocated by g_malloc().
1917  *     g_free() after usage.
1918  */
1919 gchar *
1920 gst_structure_to_string (const GstStructure * structure)
1921 {
1922   GString *s;
1923
1924   /* NOTE:  This function is potentially called by the debug system,
1925    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1926    * should be careful to avoid recursion.  This includes any functions
1927    * called by gst_structure_to_string.  In particular, calls should
1928    * not use the GST_PTR_FORMAT extension.  */
1929
1930   g_return_val_if_fail (structure != NULL, NULL);
1931
1932   /* we estimate a minimum size based on the number of fields in order to
1933    * avoid unnecessary reallocs within GString */
1934   s = g_string_sized_new (STRUCTURE_ESTIMATED_STRING_LEN (structure));
1935   g_string_append (s, g_quark_to_string (structure->name));
1936   priv_gst_structure_append_to_gstring (structure, s);
1937   return g_string_free (s, FALSE);
1938 }
1939
1940 /*
1941  * r will still point to the string. if end == next, the string will not be
1942  * null-terminated. In all other cases it will be.
1943  * end = pointer to char behind end of string, next = pointer to start of
1944  * unread data.
1945  * THIS FUNCTION MODIFIES THE STRING AND DETECTS INSIDE A NONTERMINATED STRING
1946  */
1947 static gboolean
1948 gst_structure_parse_string (gchar * s, gchar ** end, gchar ** next,
1949     gboolean unescape)
1950 {
1951   gchar *w;
1952
1953   if (*s == 0)
1954     return FALSE;
1955
1956   if (*s != '"') {
1957     int ret;
1958
1959     ret = gst_structure_parse_simple_string (s, end);
1960     *next = *end;
1961
1962     return ret;
1963   }
1964
1965   if (unescape) {
1966     w = s;
1967     s++;
1968     while (*s != '"') {
1969       if (G_UNLIKELY (*s == 0))
1970         return FALSE;
1971       if (G_UNLIKELY (*s == '\\')) {
1972         s++;
1973         if (G_UNLIKELY (*s == 0))
1974           return FALSE;
1975       }
1976       *w = *s;
1977       w++;
1978       s++;
1979     }
1980     s++;
1981   } else {
1982     /* Find the closing quotes */
1983     s++;
1984     while (*s != '"') {
1985       if (G_UNLIKELY (*s == 0))
1986         return FALSE;
1987       if (G_UNLIKELY (*s == '\\')) {
1988         s++;
1989         if (G_UNLIKELY (*s == 0))
1990           return FALSE;
1991       }
1992       s++;
1993     }
1994     s++;
1995     w = s;
1996   }
1997
1998   *end = w;
1999   *next = s;
2000
2001   return TRUE;
2002 }
2003
2004 static gboolean
2005 gst_structure_parse_range (gchar * s, gchar ** after, GValue * value,
2006     GType type)
2007 {
2008   GValue value1 = { 0 };
2009   GValue value2 = { 0 };
2010   GValue value3 = { 0 };
2011   GType range_type;
2012   gboolean ret, have_step = FALSE;
2013
2014   if (*s != '[')
2015     return FALSE;
2016   s++;
2017
2018   ret = gst_structure_parse_value (s, &s, &value1, type);
2019   if (!ret)
2020     return FALSE;
2021
2022   while (g_ascii_isspace (*s))
2023     s++;
2024
2025   if (*s != ',')
2026     return FALSE;
2027   s++;
2028
2029   while (g_ascii_isspace (*s))
2030     s++;
2031
2032   ret = gst_structure_parse_value (s, &s, &value2, type);
2033   if (!ret)
2034     return FALSE;
2035
2036   while (g_ascii_isspace (*s))
2037     s++;
2038
2039   /* optional step for int and int64 */
2040   if (G_VALUE_TYPE (&value1) == G_TYPE_INT
2041       || G_VALUE_TYPE (&value1) == G_TYPE_INT64) {
2042     if (*s == ',') {
2043       s++;
2044
2045       while (g_ascii_isspace (*s))
2046         s++;
2047
2048       ret = gst_structure_parse_value (s, &s, &value3, type);
2049       if (!ret)
2050         return FALSE;
2051
2052       while (g_ascii_isspace (*s))
2053         s++;
2054
2055       have_step = TRUE;
2056     }
2057   }
2058
2059   if (*s != ']')
2060     return FALSE;
2061   s++;
2062
2063   if (G_VALUE_TYPE (&value1) != G_VALUE_TYPE (&value2))
2064     return FALSE;
2065   if (have_step && G_VALUE_TYPE (&value1) != G_VALUE_TYPE (&value3))
2066     return FALSE;
2067
2068   if (G_VALUE_TYPE (&value1) == G_TYPE_DOUBLE) {
2069     range_type = GST_TYPE_DOUBLE_RANGE;
2070     g_value_init (value, range_type);
2071     gst_value_set_double_range (value,
2072         gst_g_value_get_double_unchecked (&value1),
2073         gst_g_value_get_double_unchecked (&value2));
2074   } else if (G_VALUE_TYPE (&value1) == G_TYPE_INT) {
2075     range_type = GST_TYPE_INT_RANGE;
2076     g_value_init (value, range_type);
2077     if (have_step)
2078       gst_value_set_int_range_step (value,
2079           gst_g_value_get_int_unchecked (&value1),
2080           gst_g_value_get_int_unchecked (&value2),
2081           gst_g_value_get_int_unchecked (&value3));
2082     else
2083       gst_value_set_int_range (value, gst_g_value_get_int_unchecked (&value1),
2084           gst_g_value_get_int_unchecked (&value2));
2085   } else if (G_VALUE_TYPE (&value1) == G_TYPE_INT64) {
2086     range_type = GST_TYPE_INT64_RANGE;
2087     g_value_init (value, range_type);
2088     if (have_step)
2089       gst_value_set_int64_range_step (value,
2090           gst_g_value_get_int64_unchecked (&value1),
2091           gst_g_value_get_int64_unchecked (&value2),
2092           gst_g_value_get_int64_unchecked (&value3));
2093     else
2094       gst_value_set_int64_range (value,
2095           gst_g_value_get_int64_unchecked (&value1),
2096           gst_g_value_get_int64_unchecked (&value2));
2097   } else if (G_VALUE_TYPE (&value1) == GST_TYPE_FRACTION) {
2098     range_type = GST_TYPE_FRACTION_RANGE;
2099     g_value_init (value, range_type);
2100     gst_value_set_fraction_range (value, &value1, &value2);
2101   } else {
2102     return FALSE;
2103   }
2104
2105   *after = s;
2106   return TRUE;
2107 }
2108
2109 static gboolean
2110 gst_structure_parse_any_list (gchar * s, gchar ** after, GValue * value,
2111     GType type, GType list_type, char begin, char end)
2112 {
2113   GValue list_value = { 0 };
2114   gboolean ret;
2115   GArray *array;
2116
2117   g_value_init (value, list_type);
2118   array = g_value_peek_pointer (value);
2119
2120   if (*s != begin)
2121     return FALSE;
2122   s++;
2123
2124   while (g_ascii_isspace (*s))
2125     s++;
2126   if (*s == end) {
2127     s++;
2128     *after = s;
2129     return TRUE;
2130   }
2131
2132   ret = gst_structure_parse_value (s, &s, &list_value, type);
2133   if (!ret)
2134     return FALSE;
2135
2136   g_array_append_val (array, list_value);
2137
2138   while (g_ascii_isspace (*s))
2139     s++;
2140
2141   while (*s != end) {
2142     if (*s != ',')
2143       return FALSE;
2144     s++;
2145
2146     while (g_ascii_isspace (*s))
2147       s++;
2148
2149     memset (&list_value, 0, sizeof (list_value));
2150     ret = gst_structure_parse_value (s, &s, &list_value, type);
2151     if (!ret)
2152       return FALSE;
2153
2154     g_array_append_val (array, list_value);
2155     while (g_ascii_isspace (*s))
2156       s++;
2157   }
2158
2159   s++;
2160
2161   *after = s;
2162   return TRUE;
2163 }
2164
2165 static gboolean
2166 gst_structure_parse_list (gchar * s, gchar ** after, GValue * value, GType type)
2167 {
2168   return gst_structure_parse_any_list (s, after, value, type, GST_TYPE_LIST,
2169       '{', '}');
2170 }
2171
2172 static gboolean
2173 gst_structure_parse_array (gchar * s, gchar ** after, GValue * value,
2174     GType type)
2175 {
2176   return gst_structure_parse_any_list (s, after, value, type,
2177       GST_TYPE_ARRAY, '<', '>');
2178 }
2179
2180 static gboolean
2181 gst_structure_parse_simple_string (gchar * str, gchar ** end)
2182 {
2183   char *s = str;
2184
2185   while (G_LIKELY (GST_ASCII_IS_STRING (*s))) {
2186     s++;
2187   }
2188
2189   *end = s;
2190
2191   return (s != str);
2192 }
2193
2194 static gboolean
2195 gst_structure_parse_field (gchar * str,
2196     gchar ** after, GstStructureField * field)
2197 {
2198   gchar *name;
2199   gchar *name_end;
2200   gchar *s;
2201   gchar c;
2202
2203   s = str;
2204
2205   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
2206     s++;
2207   name = s;
2208   if (G_UNLIKELY (!gst_structure_parse_simple_string (s, &name_end))) {
2209     GST_WARNING ("failed to parse simple string, str=%s", str);
2210     return FALSE;
2211   }
2212
2213   s = name_end;
2214   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
2215     s++;
2216
2217   if (G_UNLIKELY (*s != '=')) {
2218     GST_WARNING ("missing assignment operator in the field, str=%s", str);
2219     return FALSE;
2220   }
2221   s++;
2222
2223   c = *name_end;
2224   *name_end = '\0';
2225   field->name = g_quark_from_string (name);
2226   GST_DEBUG ("trying field name '%s'", name);
2227   *name_end = c;
2228
2229   if (G_UNLIKELY (!gst_structure_parse_value (s, &s, &field->value,
2230               G_TYPE_INVALID))) {
2231     GST_WARNING ("failed to parse value %s", str);
2232     return FALSE;
2233   }
2234
2235   *after = s;
2236   return TRUE;
2237 }
2238
2239 static gboolean
2240 gst_structure_parse_value (gchar * str,
2241     gchar ** after, GValue * value, GType default_type)
2242 {
2243   gchar *type_name;
2244   gchar *type_end;
2245   gchar *value_s;
2246   gchar *value_end;
2247   gchar *s;
2248   gchar c;
2249   int ret = 0;
2250   GType type = default_type;
2251
2252   s = str;
2253   while (g_ascii_isspace (*s))
2254     s++;
2255
2256   /* check if there's a (type_name) 'cast' */
2257   type_name = NULL;
2258   if (*s == '(') {
2259     s++;
2260     while (g_ascii_isspace (*s))
2261       s++;
2262     type_name = s;
2263     if (G_UNLIKELY (!gst_structure_parse_simple_string (s, &type_end)))
2264       return FALSE;
2265     s = type_end;
2266     while (g_ascii_isspace (*s))
2267       s++;
2268     if (G_UNLIKELY (*s != ')'))
2269       return FALSE;
2270     s++;
2271     while (g_ascii_isspace (*s))
2272       s++;
2273
2274     c = *type_end;
2275     *type_end = 0;
2276     type = gst_structure_gtype_from_abbr (type_name);
2277     GST_DEBUG ("trying type name '%s'", type_name);
2278     *type_end = c;
2279
2280     if (G_UNLIKELY (type == G_TYPE_INVALID)) {
2281       GST_WARNING ("invalid type");
2282       return FALSE;
2283     }
2284   }
2285
2286   while (g_ascii_isspace (*s))
2287     s++;
2288   if (*s == '[') {
2289     ret = gst_structure_parse_range (s, &s, value, type);
2290   } else if (*s == '{') {
2291     ret = gst_structure_parse_list (s, &s, value, type);
2292   } else if (*s == '<') {
2293     ret = gst_structure_parse_array (s, &s, value, type);
2294   } else {
2295     value_s = s;
2296
2297     if (G_UNLIKELY (type == G_TYPE_INVALID)) {
2298       GType try_types[] =
2299           { G_TYPE_INT, G_TYPE_DOUBLE, GST_TYPE_FRACTION, G_TYPE_BOOLEAN,
2300         G_TYPE_STRING
2301       };
2302       int i;
2303
2304       if (G_UNLIKELY (!gst_structure_parse_string (s, &value_end, &s, TRUE)))
2305         return FALSE;
2306       /* Set NULL terminator for deserialization */
2307       c = *value_end;
2308       *value_end = '\0';
2309
2310       for (i = 0; i < G_N_ELEMENTS (try_types); i++) {
2311         g_value_init (value, try_types[i]);
2312         ret = gst_value_deserialize (value, value_s);
2313         if (ret)
2314           break;
2315         g_value_unset (value);
2316       }
2317     } else {
2318       g_value_init (value, type);
2319
2320       if (G_UNLIKELY (!gst_structure_parse_string (s, &value_end, &s,
2321                   (type != G_TYPE_STRING))))
2322         return FALSE;
2323       /* Set NULL terminator for deserialization */
2324       c = *value_end;
2325       *value_end = '\0';
2326
2327       ret = gst_value_deserialize (value, value_s);
2328       if (G_UNLIKELY (!ret))
2329         g_value_unset (value);
2330     }
2331     *value_end = c;
2332   }
2333
2334   *after = s;
2335
2336   return ret;
2337 }
2338
2339 gboolean
2340 priv_gst_structure_parse_name (gchar * str, gchar ** start, gchar ** end,
2341     gchar ** next)
2342 {
2343   char *w;
2344   char *r;
2345
2346   r = str;
2347
2348   /* skip spaces (FIXME: _isspace treats tabs and newlines as space!) */
2349   while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
2350               && g_ascii_isspace (r[1]))))
2351     r++;
2352
2353   *start = r;
2354
2355   if (G_UNLIKELY (!gst_structure_parse_string (r, &w, &r, TRUE))) {
2356     GST_WARNING ("Failed to parse structure string '%s'", str);
2357     return FALSE;
2358   }
2359
2360   *end = w;
2361   *next = r;
2362
2363   return TRUE;
2364 }
2365
2366 gboolean
2367 priv_gst_structure_parse_fields (gchar * str, gchar ** end,
2368     GstStructure * structure)
2369 {
2370   gchar *r;
2371   GstStructureField field;
2372
2373   r = str;
2374
2375   do {
2376     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
2377                 && g_ascii_isspace (r[1]))))
2378       r++;
2379     if (*r == ';') {
2380       /* end of structure, get the next char and finish */
2381       r++;
2382       break;
2383     }
2384     if (*r == '\0') {
2385       /* accept \0 as end delimiter */
2386       break;
2387     }
2388     if (G_UNLIKELY (*r != ',')) {
2389       GST_WARNING ("Failed to find delimiter, r=%s", r);
2390       return FALSE;
2391     }
2392     r++;
2393     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
2394                 && g_ascii_isspace (r[1]))))
2395       r++;
2396
2397     memset (&field, 0, sizeof (field));
2398     if (G_UNLIKELY (!gst_structure_parse_field (r, &r, &field))) {
2399       GST_WARNING ("Failed to parse field, r=%s", r);
2400       return FALSE;
2401     }
2402     gst_structure_set_field (structure, &field);
2403   } while (TRUE);
2404
2405   *end = r;
2406
2407   return TRUE;
2408 }
2409
2410 /**
2411  * gst_structure_new_from_string:
2412  * @string: a string representation of a #GstStructure
2413  *
2414  * Creates a #GstStructure from a string representation.
2415  * If end is not %NULL, a pointer to the place inside the given string
2416  * where parsing ended will be returned.
2417  *
2418  * The current implementation of serialization will lead to unexpected results
2419  * when there are nested #GstCaps / #GstStructure deeper than one level.
2420  *
2421  * Free-function: gst_structure_free
2422  *
2423  * Returns: (transfer full) (nullable): a new #GstStructure or %NULL
2424  *     when the string could not be parsed. Free with
2425  *     gst_structure_free() after use.
2426  *
2427  * Since: 1.2
2428  */
2429 GstStructure *
2430 gst_structure_new_from_string (const gchar * string)
2431 {
2432   return gst_structure_from_string (string, NULL);
2433 }
2434
2435 /**
2436  * gst_structure_from_string:
2437  * @string: a string representation of a #GstStructure.
2438  * @end: (out) (allow-none) (transfer none) (skip): pointer to store the end of the string in.
2439  *
2440  * Creates a #GstStructure from a string representation.
2441  * If end is not %NULL, a pointer to the place inside the given string
2442  * where parsing ended will be returned.
2443  *
2444  * Free-function: gst_structure_free
2445  *
2446  * Returns: (transfer full) (nullable): a new #GstStructure or %NULL
2447  *     when the string could not be parsed. Free with
2448  *     gst_structure_free() after use.
2449  */
2450 GstStructure *
2451 gst_structure_from_string (const gchar * string, gchar ** end)
2452 {
2453   char *name;
2454   char *copy;
2455   char *w;
2456   char *r;
2457   char save;
2458   GstStructure *structure = NULL;
2459
2460   g_return_val_if_fail (string != NULL, NULL);
2461
2462   copy = g_strdup (string);
2463   r = copy;
2464
2465   if (!priv_gst_structure_parse_name (r, &name, &w, &r))
2466     goto error;
2467
2468   save = *w;
2469   *w = '\0';
2470   structure = gst_structure_new_empty (name);
2471   *w = save;
2472
2473   if (G_UNLIKELY (structure == NULL))
2474     goto error;
2475
2476   if (!priv_gst_structure_parse_fields (r, &r, structure))
2477     goto error;
2478
2479   if (end)
2480     *end = (char *) string + (r - copy);
2481   else if (*r)
2482     g_warning ("gst_structure_from_string did not consume whole string,"
2483         " but caller did not provide end pointer (\"%s\")", string);
2484
2485   g_free (copy);
2486   return structure;
2487
2488 error:
2489   if (structure)
2490     gst_structure_free (structure);
2491   g_free (copy);
2492   return NULL;
2493 }
2494
2495 static void
2496 gst_structure_transform_to_string (const GValue * src_value,
2497     GValue * dest_value)
2498 {
2499   g_return_if_fail (src_value != NULL);
2500   g_return_if_fail (dest_value != NULL);
2501
2502   dest_value->data[0].v_pointer =
2503       gst_structure_to_string (src_value->data[0].v_pointer);
2504 }
2505
2506 static GstStructure *
2507 gst_structure_copy_conditional (const GstStructure * structure)
2508 {
2509   if (structure)
2510     return gst_structure_copy (structure);
2511   return NULL;
2512 }
2513
2514 /* fixate utility functions */
2515
2516 /**
2517  * gst_structure_fixate_field_nearest_int:
2518  * @structure: a #GstStructure
2519  * @field_name: a field in @structure
2520  * @target: the target value of the fixation
2521  *
2522  * Fixates a #GstStructure by changing the given field to the nearest
2523  * integer to @target that is a subset of the existing field.
2524  *
2525  * Returns: %TRUE if the structure could be fixated
2526  */
2527 gboolean
2528 gst_structure_fixate_field_nearest_int (GstStructure * structure,
2529     const char *field_name, int target)
2530 {
2531   const GValue *value;
2532
2533   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2534   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2535
2536   value = gst_structure_get_value (structure, field_name);
2537
2538   if (G_VALUE_TYPE (value) == G_TYPE_INT) {
2539     /* already fixed */
2540     return FALSE;
2541   } else if (G_VALUE_TYPE (value) == GST_TYPE_INT_RANGE) {
2542     int x;
2543
2544     x = gst_value_get_int_range_min (value);
2545     if (target < x)
2546       target = x;
2547     x = gst_value_get_int_range_max (value);
2548     if (target > x)
2549       target = x;
2550     gst_structure_set (structure, field_name, G_TYPE_INT, target, NULL);
2551     return TRUE;
2552   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2553     const GValue *list_value;
2554     int i, n;
2555     int best = 0;
2556     int best_index = -1;
2557
2558     n = gst_value_list_get_size (value);
2559     for (i = 0; i < n; i++) {
2560       list_value = gst_value_list_get_value (value, i);
2561       if (G_VALUE_TYPE (list_value) == G_TYPE_INT) {
2562         int x = gst_g_value_get_int_unchecked (list_value);
2563
2564         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
2565           best_index = i;
2566           best = x;
2567         }
2568       }
2569     }
2570     if (best_index != -1) {
2571       gst_structure_set (structure, field_name, G_TYPE_INT, best, NULL);
2572       return TRUE;
2573     }
2574     return FALSE;
2575   }
2576
2577   return FALSE;
2578 }
2579
2580 /**
2581  * gst_structure_fixate_field_nearest_double:
2582  * @structure: a #GstStructure
2583  * @field_name: a field in @structure
2584  * @target: the target value of the fixation
2585  *
2586  * Fixates a #GstStructure by changing the given field to the nearest
2587  * double to @target that is a subset of the existing field.
2588  *
2589  * Returns: %TRUE if the structure could be fixated
2590  */
2591 gboolean
2592 gst_structure_fixate_field_nearest_double (GstStructure * structure,
2593     const char *field_name, double target)
2594 {
2595   const GValue *value;
2596
2597   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2598   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2599
2600   value = gst_structure_get_value (structure, field_name);
2601
2602   if (G_VALUE_TYPE (value) == G_TYPE_DOUBLE) {
2603     /* already fixed */
2604     return FALSE;
2605   } else if (G_VALUE_TYPE (value) == GST_TYPE_DOUBLE_RANGE) {
2606     double x;
2607
2608     x = gst_value_get_double_range_min (value);
2609     if (target < x)
2610       target = x;
2611     x = gst_value_get_double_range_max (value);
2612     if (target > x)
2613       target = x;
2614     gst_structure_set (structure, field_name, G_TYPE_DOUBLE, target, NULL);
2615     return TRUE;
2616   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2617     const GValue *list_value;
2618     int i, n;
2619     double best = 0;
2620     int best_index = -1;
2621
2622     n = gst_value_list_get_size (value);
2623     for (i = 0; i < n; i++) {
2624       list_value = gst_value_list_get_value (value, i);
2625       if (G_VALUE_TYPE (list_value) == G_TYPE_DOUBLE) {
2626         double x = gst_g_value_get_double_unchecked (list_value);
2627
2628         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
2629           best_index = i;
2630           best = x;
2631         }
2632       }
2633     }
2634     if (best_index != -1) {
2635       gst_structure_set (structure, field_name, G_TYPE_DOUBLE, best, NULL);
2636       return TRUE;
2637     }
2638     return FALSE;
2639   }
2640
2641   return FALSE;
2642
2643 }
2644
2645 /**
2646  * gst_structure_fixate_field_boolean:
2647  * @structure: a #GstStructure
2648  * @field_name: a field in @structure
2649  * @target: the target value of the fixation
2650  *
2651  * Fixates a #GstStructure by changing the given @field_name field to the given
2652  * @target boolean if that field is not fixed yet.
2653  *
2654  * Returns: %TRUE if the structure could be fixated
2655  */
2656 gboolean
2657 gst_structure_fixate_field_boolean (GstStructure * structure,
2658     const char *field_name, gboolean target)
2659 {
2660   const GValue *value;
2661
2662   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2663   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2664
2665   value = gst_structure_get_value (structure, field_name);
2666
2667   if (G_VALUE_TYPE (value) == G_TYPE_BOOLEAN) {
2668     /* already fixed */
2669     return FALSE;
2670   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2671     const GValue *list_value;
2672     int i, n;
2673     int best = 0;
2674     int best_index = -1;
2675
2676     n = gst_value_list_get_size (value);
2677     for (i = 0; i < n; i++) {
2678       list_value = gst_value_list_get_value (value, i);
2679       if (G_VALUE_TYPE (list_value) == G_TYPE_BOOLEAN) {
2680         gboolean x = gst_g_value_get_boolean_unchecked (list_value);
2681
2682         if (best_index == -1 || x == target) {
2683           best_index = i;
2684           best = x;
2685         }
2686       }
2687     }
2688     if (best_index != -1) {
2689       gst_structure_set (structure, field_name, G_TYPE_BOOLEAN, best, NULL);
2690       return TRUE;
2691     }
2692     return FALSE;
2693   }
2694
2695   return FALSE;
2696 }
2697
2698 /**
2699  * gst_structure_fixate_field_string:
2700  * @structure: a #GstStructure
2701  * @field_name: a field in @structure
2702  * @target: the target value of the fixation
2703  *
2704  * Fixates a #GstStructure by changing the given @field_name field to the given
2705  * @target string if that field is not fixed yet.
2706  *
2707  * Returns: %TRUE if the structure could be fixated
2708  */
2709 gboolean
2710 gst_structure_fixate_field_string (GstStructure * structure,
2711     const gchar * field_name, const gchar * target)
2712 {
2713   const GValue *value;
2714
2715   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2716   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2717
2718   value = gst_structure_get_value (structure, field_name);
2719
2720   if (G_VALUE_TYPE (value) == G_TYPE_STRING) {
2721     /* already fixed */
2722     return FALSE;
2723   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2724     const GValue *list_value;
2725     int i, n;
2726     const gchar *best = NULL;
2727     int best_index = -1;
2728
2729     n = gst_value_list_get_size (value);
2730     for (i = 0; i < n; i++) {
2731       list_value = gst_value_list_get_value (value, i);
2732       if (G_VALUE_TYPE (list_value) == G_TYPE_STRING) {
2733         const gchar *x = g_value_get_string (list_value);
2734
2735         if (best_index == -1 || g_str_equal (x, target)) {
2736           best_index = i;
2737           best = x;
2738         }
2739       }
2740     }
2741     if (best_index != -1) {
2742       gst_structure_set (structure, field_name, G_TYPE_STRING, best, NULL);
2743       return TRUE;
2744     }
2745     return FALSE;
2746   }
2747
2748   return FALSE;
2749 }
2750
2751 /**
2752  * gst_structure_fixate_field_nearest_fraction:
2753  * @structure: a #GstStructure
2754  * @field_name: a field in @structure
2755  * @target_numerator: The numerator of the target value of the fixation
2756  * @target_denominator: The denominator of the target value of the fixation
2757  *
2758  * Fixates a #GstStructure by changing the given field to the nearest
2759  * fraction to @target_numerator/@target_denominator that is a subset
2760  * of the existing field.
2761  *
2762  * Returns: %TRUE if the structure could be fixated
2763  */
2764 gboolean
2765 gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
2766     const char *field_name, const gint target_numerator,
2767     const gint target_denominator)
2768 {
2769   const GValue *value;
2770
2771   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
2772   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2773   g_return_val_if_fail (target_denominator != 0, FALSE);
2774
2775   value = gst_structure_get_value (structure, field_name);
2776
2777   if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION) {
2778     /* already fixed */
2779     return FALSE;
2780   } else if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION_RANGE) {
2781     const GValue *x, *new_value;
2782     GValue target = { 0 };
2783     g_value_init (&target, GST_TYPE_FRACTION);
2784     gst_value_set_fraction (&target, target_numerator, target_denominator);
2785
2786     new_value = &target;
2787     x = gst_value_get_fraction_range_min (value);
2788     if (gst_value_compare (&target, x) == GST_VALUE_LESS_THAN)
2789       new_value = x;
2790     x = gst_value_get_fraction_range_max (value);
2791     if (gst_value_compare (&target, x) == GST_VALUE_GREATER_THAN)
2792       new_value = x;
2793
2794     gst_structure_set_value (structure, field_name, new_value);
2795     g_value_unset (&target);
2796     return TRUE;
2797   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2798     const GValue *list_value;
2799     int i, n;
2800     const GValue *best = NULL;
2801     gdouble target;
2802     gdouble cur_diff;
2803     gdouble best_diff = G_MAXDOUBLE;
2804
2805     target = (gdouble) target_numerator / (gdouble) target_denominator;
2806
2807     GST_DEBUG ("target %g, best %g", target, best_diff);
2808
2809     best = NULL;
2810
2811     n = gst_value_list_get_size (value);
2812     for (i = 0; i < n; i++) {
2813       list_value = gst_value_list_get_value (value, i);
2814       if (G_VALUE_TYPE (list_value) == GST_TYPE_FRACTION) {
2815         gint num, denom;
2816         gdouble list_double;
2817
2818         num = gst_value_get_fraction_numerator (list_value);
2819         denom = gst_value_get_fraction_denominator (list_value);
2820
2821         list_double = ((gdouble) num / (gdouble) denom);
2822         cur_diff = target - list_double;
2823
2824         GST_DEBUG ("curr diff %g, list %g", cur_diff, list_double);
2825
2826         if (cur_diff < 0)
2827           cur_diff = -cur_diff;
2828
2829         if (!best || cur_diff < best_diff) {
2830           GST_DEBUG ("new best %g", list_double);
2831           best = list_value;
2832           best_diff = cur_diff;
2833         }
2834       }
2835     }
2836     if (best != NULL) {
2837       gst_structure_set_value (structure, field_name, best);
2838       return TRUE;
2839     }
2840   }
2841
2842   return FALSE;
2843 }
2844
2845 static gboolean
2846 default_fixate (GQuark field_id, const GValue * value, gpointer data)
2847 {
2848   GstStructure *s = data;
2849   GValue v = { 0 };
2850
2851   if (gst_value_fixate (&v, value)) {
2852     gst_structure_id_take_value (s, field_id, &v);
2853   }
2854   return TRUE;
2855 }
2856
2857 /**
2858  * gst_structure_fixate_field:
2859  * @structure: a #GstStructure
2860  * @field_name: a field in @structure
2861  *
2862  * Fixates a #GstStructure by changing the given field with its fixated value.
2863  *
2864  * Returns: %TRUE if the structure field could be fixated
2865  */
2866 gboolean
2867 gst_structure_fixate_field (GstStructure * structure, const char *field_name)
2868 {
2869   GstStructureField *field;
2870
2871   g_return_val_if_fail (structure != NULL, FALSE);
2872   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
2873
2874   if (!(field = gst_structure_get_field (structure, field_name)))
2875     return FALSE;
2876
2877   return default_fixate (field->name, &field->value, structure);
2878 }
2879
2880 /* our very own version of G_VALUE_LCOPY that allows NULL return locations
2881  * (useful for message parsing functions where the return location is user
2882  * supplied and the user may pass %NULL if the value isn't of interest) */
2883 #define GST_VALUE_LCOPY(value, var_args, flags, __error, fieldname)           \
2884 G_STMT_START {                                                                \
2885   const GValue *_value = (value);                                             \
2886   guint _flags = (flags);                                                     \
2887   GType _value_type = G_VALUE_TYPE (_value);                                  \
2888   GTypeValueTable *_vtable = g_type_value_table_peek (_value_type);           \
2889   const gchar *_lcopy_format = _vtable->lcopy_format;                         \
2890   GTypeCValue _cvalues[G_VALUE_COLLECT_FORMAT_MAX_LENGTH] = { { 0, }, };      \
2891   guint _n_values = 0;                                                        \
2892                                                                               \
2893   while (*_lcopy_format != '\0') {                                            \
2894     g_assert (*_lcopy_format == G_VALUE_COLLECT_POINTER);                     \
2895     _cvalues[_n_values++].v_pointer = va_arg ((var_args), gpointer);          \
2896     _lcopy_format++;                                                          \
2897   }                                                                           \
2898   if (_n_values == 2 && !!_cvalues[0].v_pointer != !!_cvalues[1].v_pointer) { \
2899     *(__error) = g_strdup_printf ("either all or none of the return "         \
2900         "locations for field '%s' need to be NULL", fieldname);               \
2901   } else if (_cvalues[0].v_pointer != NULL) {                                 \
2902     *(__error) = _vtable->lcopy_value (_value, _n_values, _cvalues, _flags);  \
2903   }                                                                           \
2904 } G_STMT_END
2905
2906 /**
2907  * gst_structure_get_valist:
2908  * @structure: a #GstStructure
2909  * @first_fieldname: the name of the first field to read
2910  * @args: variable arguments
2911  *
2912  * Parses the variable arguments and reads fields from @structure accordingly.
2913  * valist-variant of gst_structure_get(). Look at the documentation of
2914  * gst_structure_get() for more details.
2915  *
2916  * Returns: %TRUE, or %FALSE if there was a problem reading any of the fields
2917  */
2918 gboolean
2919 gst_structure_get_valist (const GstStructure * structure,
2920     const char *first_fieldname, va_list args)
2921 {
2922   const char *field_name;
2923   GType expected_type = G_TYPE_INVALID;
2924
2925   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
2926   g_return_val_if_fail (first_fieldname != NULL, FALSE);
2927
2928   field_name = first_fieldname;
2929   while (field_name) {
2930     const GValue *val = NULL;
2931     gchar *err = NULL;
2932
2933     expected_type = va_arg (args, GType);
2934
2935     val = gst_structure_get_value (structure, field_name);
2936
2937     if (val == NULL)
2938       goto no_such_field;
2939
2940     if (G_VALUE_TYPE (val) != expected_type)
2941       goto wrong_type;
2942
2943     GST_VALUE_LCOPY (val, args, 0, &err, field_name);
2944     if (err) {
2945       g_warning ("%s: %s", G_STRFUNC, err);
2946       g_free (err);
2947       return FALSE;
2948     }
2949
2950     field_name = va_arg (args, const gchar *);
2951   }
2952
2953   return TRUE;
2954
2955 /* ERRORS */
2956 no_such_field:
2957   {
2958     GST_INFO ("Expected field '%s' in structure: %" GST_PTR_FORMAT,
2959         field_name, structure);
2960     return FALSE;
2961   }
2962 wrong_type:
2963   {
2964     GST_INFO ("Expected field '%s' in structure to be of type '%s', but "
2965         "field was of type '%s': %" GST_PTR_FORMAT, field_name,
2966         GST_STR_NULL (g_type_name (expected_type)),
2967         G_VALUE_TYPE_NAME (gst_structure_get_value (structure, field_name)),
2968         structure);
2969     return FALSE;
2970   }
2971 }
2972
2973 /**
2974  * gst_structure_id_get_valist:
2975  * @structure: a #GstStructure
2976  * @first_field_id: the quark of the first field to read
2977  * @args: variable arguments
2978  *
2979  * Parses the variable arguments and reads fields from @structure accordingly.
2980  * valist-variant of gst_structure_id_get(). Look at the documentation of
2981  * gst_structure_id_get() for more details.
2982  *
2983  * Returns: %TRUE, or %FALSE if there was a problem reading any of the fields
2984  */
2985 gboolean
2986 gst_structure_id_get_valist (const GstStructure * structure,
2987     GQuark first_field_id, va_list args)
2988 {
2989   GQuark field_id;
2990   GType expected_type = G_TYPE_INVALID;
2991
2992   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
2993   g_return_val_if_fail (first_field_id != 0, FALSE);
2994
2995   field_id = first_field_id;
2996   while (field_id) {
2997     const GValue *val = NULL;
2998     gchar *err = NULL;
2999
3000     expected_type = va_arg (args, GType);
3001
3002     val = gst_structure_id_get_value (structure, field_id);
3003
3004     if (val == NULL)
3005       goto no_such_field;
3006
3007     if (G_VALUE_TYPE (val) != expected_type)
3008       goto wrong_type;
3009
3010     GST_VALUE_LCOPY (val, args, 0, &err, g_quark_to_string (field_id));
3011     if (err) {
3012       g_warning ("%s: %s", G_STRFUNC, err);
3013       g_free (err);
3014       return FALSE;
3015     }
3016
3017     field_id = va_arg (args, GQuark);
3018   }
3019
3020   return TRUE;
3021
3022 /* ERRORS */
3023 no_such_field:
3024   {
3025     GST_DEBUG ("Expected field '%s' in structure: %" GST_PTR_FORMAT,
3026         GST_STR_NULL (g_quark_to_string (field_id)), structure);
3027     return FALSE;
3028   }
3029 wrong_type:
3030   {
3031     GST_DEBUG ("Expected field '%s' in structure to be of type '%s', but "
3032         "field was of type '%s': %" GST_PTR_FORMAT,
3033         g_quark_to_string (field_id),
3034         GST_STR_NULL (g_type_name (expected_type)),
3035         G_VALUE_TYPE_NAME (gst_structure_id_get_value (structure, field_id)),
3036         structure);
3037     return FALSE;
3038   }
3039 }
3040
3041 /**
3042  * gst_structure_get:
3043  * @structure: a #GstStructure
3044  * @first_fieldname: the name of the first field to read
3045  * @...: variable arguments
3046  *
3047  * Parses the variable arguments and reads fields from @structure accordingly.
3048  * Variable arguments should be in the form field name, field type
3049  * (as a GType), pointer(s) to a variable(s) to hold the return value(s).
3050  * The last variable argument should be %NULL.
3051  *
3052  * For refcounted (mini)objects you will receive a new reference which
3053  * you must release with a suitable _unref() when no longer needed. For
3054  * strings and boxed types you will receive a copy which you will need to
3055  * release with either g_free() or the suitable function for the boxed type.
3056  *
3057  * Returns: %FALSE if there was a problem reading any of the fields (e.g.
3058  *     because the field requested did not exist, or was of a type other
3059  *     than the type specified), otherwise %TRUE.
3060  */
3061 gboolean
3062 gst_structure_get (const GstStructure * structure, const char *first_fieldname,
3063     ...)
3064 {
3065   gboolean ret;
3066   va_list args;
3067
3068   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
3069   g_return_val_if_fail (first_fieldname != NULL, FALSE);
3070
3071   va_start (args, first_fieldname);
3072   ret = gst_structure_get_valist (structure, first_fieldname, args);
3073   va_end (args);
3074
3075   return ret;
3076 }
3077
3078 /**
3079  * gst_structure_id_get:
3080  * @structure: a #GstStructure
3081  * @first_field_id: the quark of the first field to read
3082  * @...: variable arguments
3083  *
3084  * Parses the variable arguments and reads fields from @structure accordingly.
3085  * Variable arguments should be in the form field id quark, field type
3086  * (as a GType), pointer(s) to a variable(s) to hold the return value(s).
3087  * The last variable argument should be %NULL (technically it should be a
3088  * 0 quark, but we require %NULL so compilers that support it can check for
3089  * the %NULL terminator and warn if it's not there).
3090  *
3091  * This function is just like gst_structure_get() only that it is slightly
3092  * more efficient since it saves the string-to-quark lookup in the global
3093  * quark hashtable.
3094  *
3095  * For refcounted (mini)objects you will receive a new reference which
3096  * you must release with a suitable _unref() when no longer needed. For
3097  * strings and boxed types you will receive a copy which you will need to
3098  * release with either g_free() or the suitable function for the boxed type.
3099  *
3100  * Returns: %FALSE if there was a problem reading any of the fields (e.g.
3101  *     because the field requested did not exist, or was of a type other
3102  *     than the type specified), otherwise %TRUE.
3103  */
3104 gboolean
3105 gst_structure_id_get (const GstStructure * structure, GQuark first_field_id,
3106     ...)
3107 {
3108   gboolean ret;
3109   va_list args;
3110
3111   g_return_val_if_fail (GST_IS_STRUCTURE (structure), FALSE);
3112   g_return_val_if_fail (first_field_id != 0, FALSE);
3113
3114   va_start (args, first_field_id);
3115   ret = gst_structure_id_get_valist (structure, first_field_id, args);
3116   va_end (args);
3117
3118   return ret;
3119 }
3120
3121 static gboolean
3122 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
3123     gpointer data)
3124 {
3125   const GstStructure *struct1 = (const GstStructure *) data;
3126   const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
3127
3128   if (G_UNLIKELY (val1 == NULL))
3129     return FALSE;
3130   if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
3131     return TRUE;
3132   }
3133
3134   return FALSE;
3135 }
3136
3137 /**
3138  * gst_structure_is_equal:
3139  * @structure1: a #GstStructure.
3140  * @structure2: a #GstStructure.
3141  *
3142  * Tests if the two #GstStructure are equal.
3143  *
3144  * Returns: %TRUE if the two structures have the same name and field.
3145  **/
3146 gboolean
3147 gst_structure_is_equal (const GstStructure * structure1,
3148     const GstStructure * structure2)
3149 {
3150   g_return_val_if_fail (GST_IS_STRUCTURE (structure1), FALSE);
3151   g_return_val_if_fail (GST_IS_STRUCTURE (structure2), FALSE);
3152
3153   if (G_UNLIKELY (structure1 == structure2))
3154     return TRUE;
3155
3156   if (structure1->name != structure2->name) {
3157     return FALSE;
3158   }
3159   if (GST_STRUCTURE_FIELDS (structure1)->len !=
3160       GST_STRUCTURE_FIELDS (structure2)->len) {
3161     return FALSE;
3162   }
3163
3164   return gst_structure_foreach (structure1, gst_structure_is_equal_foreach,
3165       (gpointer) structure2);
3166 }
3167
3168
3169 typedef struct
3170 {
3171   GstStructure *dest;
3172   const GstStructure *intersect;
3173 }
3174 IntersectData;
3175
3176 static gboolean
3177 gst_structure_intersect_field1 (GQuark id, const GValue * val1, gpointer data)
3178 {
3179   IntersectData *idata = (IntersectData *) data;
3180   const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
3181
3182   if (G_UNLIKELY (val2 == NULL)) {
3183     gst_structure_id_set_value (idata->dest, id, val1);
3184   } else {
3185     GValue dest_value = { 0 };
3186     if (gst_value_intersect (&dest_value, val1, val2)) {
3187       gst_structure_id_take_value (idata->dest, id, &dest_value);
3188     } else {
3189       return FALSE;
3190     }
3191   }
3192   return TRUE;
3193 }
3194
3195 static gboolean
3196 gst_structure_intersect_field2 (GQuark id, const GValue * val1, gpointer data)
3197 {
3198   IntersectData *idata = (IntersectData *) data;
3199   const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
3200
3201   if (G_UNLIKELY (val2 == NULL)) {
3202     gst_structure_id_set_value (idata->dest, id, val1);
3203   }
3204   return TRUE;
3205 }
3206
3207 /**
3208  * gst_structure_intersect:
3209  * @struct1: a #GstStructure
3210  * @struct2: a #GstStructure
3211  *
3212  * Intersects @struct1 and @struct2 and returns the intersection.
3213  *
3214  * Returns: Intersection of @struct1 and @struct2
3215  */
3216 GstStructure *
3217 gst_structure_intersect (const GstStructure * struct1,
3218     const GstStructure * struct2)
3219 {
3220   IntersectData data;
3221
3222   g_assert (struct1 != NULL);
3223   g_assert (struct2 != NULL);
3224
3225   if (G_UNLIKELY (struct1->name != struct2->name))
3226     return NULL;
3227
3228   /* copy fields from struct1 which we have not in struct2 to target
3229    * intersect if we have the field in both */
3230   data.dest = gst_structure_new_id_empty (struct1->name);
3231   data.intersect = struct2;
3232   if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
3233               gst_structure_intersect_field1, &data)))
3234     goto error;
3235
3236   /* copy fields from struct2 which we have not in struct1 to target */
3237   data.intersect = struct1;
3238   if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
3239               gst_structure_intersect_field2, &data)))
3240     goto error;
3241
3242   return data.dest;
3243
3244 error:
3245   gst_structure_free (data.dest);
3246   return NULL;
3247 }
3248
3249 static gboolean
3250 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
3251     gpointer data)
3252 {
3253   GstStructure *other = (GstStructure *) data;
3254   const GValue *val2 = gst_structure_id_get_value (other, id);
3255
3256   if (G_LIKELY (val2)) {
3257     if (!gst_value_can_intersect (val1, val2)) {
3258       return FALSE;
3259     } else {
3260       gint eq = gst_value_compare (val1, val2);
3261
3262       if (eq == GST_VALUE_UNORDERED) {
3263         /* we need to try interseting */
3264         if (!gst_value_intersect (NULL, val1, val2)) {
3265           return FALSE;
3266         }
3267       } else if (eq != GST_VALUE_EQUAL) {
3268         return FALSE;
3269       }
3270     }
3271   }
3272   return TRUE;
3273 }
3274
3275 /**
3276  * gst_structure_can_intersect:
3277  * @struct1: a #GstStructure
3278  * @struct2: a #GstStructure
3279  *
3280  * Tries intersecting @struct1 and @struct2 and reports whether the result
3281  * would not be empty.
3282  *
3283  * Returns: %TRUE if intersection would not be empty
3284  */
3285 gboolean
3286 gst_structure_can_intersect (const GstStructure * struct1,
3287     const GstStructure * struct2)
3288 {
3289   g_return_val_if_fail (GST_IS_STRUCTURE (struct1), FALSE);
3290   g_return_val_if_fail (GST_IS_STRUCTURE (struct2), FALSE);
3291
3292   if (G_UNLIKELY (struct1->name != struct2->name))
3293     return FALSE;
3294
3295   /* tries to intersect if we have the field in both */
3296   return gst_structure_foreach ((GstStructure *) struct1,
3297       gst_caps_structure_can_intersect_field, (gpointer) struct2);
3298 }
3299
3300 static gboolean
3301 gst_caps_structure_is_superset_field (GQuark field_id, const GValue * value,
3302     gpointer user_data)
3303 {
3304   GstStructure *subset = user_data;
3305   const GValue *other;
3306   int comparison;
3307
3308   if (!(other = gst_structure_id_get_value (subset, field_id)))
3309     /* field is missing in the subset => no subset */
3310     return FALSE;
3311
3312   comparison = gst_value_compare (value, other);
3313
3314   /* equal values are subset */
3315   if (comparison == GST_VALUE_EQUAL)
3316     return TRUE;
3317
3318   /* ordered, but unequal, values are not */
3319   if (comparison != GST_VALUE_UNORDERED)
3320     return FALSE;
3321
3322   return gst_value_is_subset (other, value);
3323 }
3324
3325 /**
3326  * gst_structure_is_subset:
3327  * @subset: a #GstStructure
3328  * @superset: a potentially greater #GstStructure
3329  *
3330  * Checks if @subset is a subset of @superset, i.e. has the same
3331  * structure name and for all fields that are existing in @superset,
3332  * @subset has a value that is a subset of the value in @superset.
3333  *
3334  * Returns: %TRUE if @subset is a subset of @superset
3335  */
3336 gboolean
3337 gst_structure_is_subset (const GstStructure * subset,
3338     const GstStructure * superset)
3339 {
3340   if ((superset->name != subset->name) ||
3341       (gst_structure_n_fields (superset) > gst_structure_n_fields (subset)))
3342     return FALSE;
3343
3344   return gst_structure_foreach ((GstStructure *) superset,
3345       gst_caps_structure_is_superset_field, (gpointer) subset);
3346 }
3347
3348
3349 /**
3350  * gst_structure_fixate:
3351  * @structure: a #GstStructure
3352  *
3353  * Fixate all values in @structure using gst_value_fixate().
3354  * @structure will be modified in-place and should be writable.
3355  */
3356 void
3357 gst_structure_fixate (GstStructure * structure)
3358 {
3359   g_return_if_fail (GST_IS_STRUCTURE (structure));
3360
3361   gst_structure_foreach (structure, default_fixate, structure);
3362 }