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