gst/gststructure.c

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