gst/gststructure.c

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