gst/gststructure.c

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