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., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 /**
  23  * SECTION:gststructure
  24  * @short_description: Generic structure containing fields of names and values
  25  * @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery
  26  *
  27  * A #GstStructure is a collection of key/value pairs. The keys are expressed as
  28  * GQuarks and the values can be of any GType.
  29  *
  30  * In addition to the key/value pairs, a #GstStructure also has a name.
  31  *
  32  * #GstStructure is used by various GStreamer subsystems to store information in
  33  * a flexible an extensible way. A #GstStructure does not have a refcount because it
  34  * usually is part of a higher level object such as #GstCaps. It provides a means to
  35  * enforce mutability using the refcount of the parent with the
  36  * gst_structure_set_parent_refcount() method.
  37  *
  38  * A #GstStructure can be created with gst_structure_empty_new() or gst_structure_new(),
  39  * which both take a name and an optional set of key/value pairs along with the types
  40  * of the values.
  41  *
  42  * Field values can be changed with gst_structure_set_value() or gst_structure_set().
  43  *
  44  * Field values can be retrieved with gst_structure_get_value() or the more convenient
  45  * gst_structure_get_*() functions.
  46  *
  47  * Fields can be removed with gst_structure_remove_field() or gst_structure_remove_fields().
  48  *
  49  * Last reviewed on 2005-11-09 (0.9.4)
  50  */
  51
  52 #ifdef HAVE_CONFIG_H
  53 #include "config.h"
  54 #endif
  55
  56 #include <string.h>
  57
  58 #include "gst_private.h"
  59 #include <gst/gst.h>
  60 #include <gobject/gvaluecollector.h>
  61
  62 typedef struct _GstStructureField GstStructureField;
  63
  64 struct _GstStructureField
  65 {
  66   GQuark name;
  67   GValue value;
  68 };
  69
  70 #define GST_STRUCTURE_FIELD(structure, index) \
  71     &g_array_index((structure)->fields, GstStructureField, (index))
  72
  73 #define IS_MUTABLE(structure) \
  74     (!(structure)->parent_refcount || \
  75      g_atomic_int_get ((structure)->parent_refcount) == 1)
  76
  77 static void gst_structure_set_field (GstStructure * structure,
  78     GstStructureField * field);
  79 static GstStructureField *gst_structure_get_field (const GstStructure *
  80     structure, const gchar * fieldname);
  81 static GstStructureField *gst_structure_id_get_field (const GstStructure *
  82     structure, GQuark field);
  83 static void gst_structure_transform_to_string (const GValue * src_value,
  84     GValue * dest_value);
  85 static GstStructure *gst_structure_copy_conditional (const GstStructure *
  86     structure);
  87 static gboolean gst_structure_parse_value (gchar * str, gchar ** after,
  88     GValue * value, GType default_type);
  89 static gboolean gst_structure_parse_simple_string (gchar * s, gchar ** end);
  90
  91 GType
  92 gst_structure_get_type (void)
  93 {
  94   static GType gst_structure_type = 0;
  95
  96   if (G_UNLIKELY (gst_structure_type == 0)) {
  97     gst_structure_type = g_boxed_type_register_static ("GstStructure",
  98         (GBoxedCopyFunc) gst_structure_copy_conditional,
  99         (GBoxedFreeFunc) gst_structure_free);
 100
 101     g_value_register_transform_func (gst_structure_type, G_TYPE_STRING,
 102         gst_structure_transform_to_string);
 103   }
 104
 105   return gst_structure_type;
 106 }
 107
 108 static GstStructure *
 109 gst_structure_id_empty_new_with_size (GQuark quark, guint prealloc)
 110 {
 111   GstStructure *structure;
 112
 113   structure = g_new0 (GstStructure, 1);
 114   structure->type = gst_structure_get_type ();
 115   structure->name = quark;
 116   structure->fields =
 117       g_array_sized_new (FALSE, TRUE, sizeof (GstStructureField), prealloc);
 118
 119   return structure;
 120 }
 121
 122 /**
 123  * gst_structure_id_empty_new:
 124  * @quark: name of new structure
 125  *
 126  * Creates a new, empty #GstStructure with the given name as a GQuark.
 127  *
 128  * Returns: a new, empty #GstStructure
 129  */
 130 GstStructure *
 131 gst_structure_id_empty_new (GQuark quark)
 132 {
 133   g_return_val_if_fail (quark != 0, NULL);
 134
 135   return gst_structure_id_empty_new_with_size (quark, 0);
 136 }
 137
 138 /**
 139  * gst_structure_empty_new:
 140  * @name: name of new structure
 141  *
 142  * Creates a new, empty #GstStructure with the given name.
 143  *
 144  * Returns: a new, empty #GstStructure
 145  */
 146 GstStructure *
 147 gst_structure_empty_new (const gchar * name)
 148 {
 149   g_return_val_if_fail (name != NULL, NULL);
 150
 151   return gst_structure_id_empty_new_with_size (g_quark_from_string (name), 0);
 152 }
 153
 154 /**
 155  * gst_structure_new:
 156  * @name: name of new structure
 157  * @firstfield: name of first field to set
 158  * @...: additional arguments
 159  *
 160  * Creates a new #GstStructure with the given name.  Parses the
 161  * list of variable arguments and sets fields to the values listed.
 162  * Variable arguments should be passed as field name, field type,
 163  * and value.  Last variable argument should be NULL.
 164  *
 165  * Returns: a new #GstStructure
 166  */
 167 GstStructure *
 168 gst_structure_new (const gchar * name, const gchar * firstfield, ...)
 169 {
 170   GstStructure *structure;
 171   va_list varargs;
 172
 173   g_return_val_if_fail (name != NULL, NULL);
 174
 175   va_start (varargs, firstfield);
 176
 177   structure = gst_structure_new_valist (name, firstfield, varargs);
 178
 179   va_end (varargs);
 180
 181   return structure;
 182 }
 183
 184 /**
 185  * gst_structure_new_valist:
 186  * @name: name of new structure
 187  * @firstfield: name of first field to set
 188  * @varargs: variable argument list
 189  *
 190  * Creates a new #GstStructure with the given name.  Structure fields
 191  * are set according to the varargs in a manner similar to
 192  * @gst_structure_new.
 193  *
 194  * Returns: a new #GstStructure
 195  */
 196 GstStructure *
 197 gst_structure_new_valist (const gchar * name,
 198     const gchar * firstfield, va_list varargs)
 199 {
 200   GstStructure *structure;
 201
 202   g_return_val_if_fail (name != NULL, NULL);
 203
 204   structure = gst_structure_empty_new (name);
 205   gst_structure_set_valist (structure, firstfield, varargs);
 206
 207   return structure;
 208 }
 209
 210 /**
 211  * gst_structure_set_parent_refcount:
 212  * @structure: a #GstStructure
 213  * @refcount: a pointer to the parent's refcount
 214  *
 215  * Sets the parent_refcount field of #GstStructure. This field is used to
 216  * determine whether a structure is mutable or not. This function should only be
 217  * called by code implementing parent objects of #GstStructure, as described in
 218  * the MT Refcounting section of the design documents.
 219  */
 220 void
 221 gst_structure_set_parent_refcount (GstStructure * structure, int *refcount)
 222 {
 223   g_return_if_fail (structure != NULL);
 224
 225   /* if we have a parent_refcount already, we can only clear
 226    * if with a NULL refcount */
 227   if (structure->parent_refcount)
 228     g_return_if_fail (refcount == NULL);
 229   else
 230     g_return_if_fail (refcount != NULL);
 231
 232   structure->parent_refcount = refcount;
 233 }
 234
 235 /**
 236  * gst_structure_copy:
 237  * @structure: a #GstStructure to duplicate
 238  *
 239  * Duplicates a #GstStructure and all its fields and values.
 240  *
 241  * Returns: a new #GstStructure.
 242  */
 243 GstStructure *
 244 gst_structure_copy (const GstStructure * structure)
 245 {
 246   GstStructure *new_structure;
 247   GstStructureField *field;
 248   guint i;
 249
 250   g_return_val_if_fail (structure != NULL, NULL);
 251
 252   new_structure =
 253       gst_structure_id_empty_new_with_size (structure->name,
 254       structure->fields->len);
 255
 256   for (i = 0; i < structure->fields->len; i++) {
 257     GstStructureField new_field = { 0 };
 258
 259     field = GST_STRUCTURE_FIELD (structure, i);
 260
 261     new_field.name = field->name;
 262     gst_value_init_and_copy (&new_field.value, &field->value);
 263     g_array_append_val (new_structure->fields, new_field);
 264   }
 265
 266   return new_structure;
 267 }
 268
 269 /**
 270  * gst_structure_free:
 271  * @structure: the #GstStructure to free
 272  *
 273  * Frees a #GstStructure and all its fields and values. The structure must not
 274  * have a parent when this function is called.
 275  */
 276 void
 277 gst_structure_free (GstStructure * structure)
 278 {
 279   GstStructureField *field;
 280   guint i;
 281
 282   g_return_if_fail (structure != NULL);
 283   g_return_if_fail (structure->parent_refcount == NULL);
 284
 285   for (i = 0; i < structure->fields->len; i++) {
 286     field = GST_STRUCTURE_FIELD (structure, i);
 287
 288     if (G_IS_VALUE (&field->value)) {
 289       g_value_unset (&field->value);
 290     }
 291   }
 292   g_array_free (structure->fields, TRUE);
 293 #ifdef USE_POISONING
 294   memset (structure, 0xff, sizeof (GstStructure));
 295 #endif
 296   g_free (structure);
 297 }
 298
 299 /**
 300  * gst_structure_get_name:
 301  * @structure: a #GstStructure
 302  *
 303  * Get the name of @structure as a string.
 304  *
 305  * Returns: the name of the structure.
 306  */
 307 const gchar *
 308 gst_structure_get_name (const GstStructure * structure)
 309 {
 310   g_return_val_if_fail (structure != NULL, NULL);
 311
 312   return g_quark_to_string (structure->name);
 313 }
 314
 315 /**
 316  * gst_structure_has_name:
 317  * @structure: a #GstStructure
 318  * @name: structure name to check for
 319  *
 320  * Checks if the structure has the given name
 321  *
 322  * Returns: TRUE if @name matches the name of the structure.
 323  */
 324 gboolean
 325 gst_structure_has_name (const GstStructure * structure, const gchar * name)
 326 {
 327   const gchar *structure_name;
 328
 329   g_return_val_if_fail (structure != NULL, FALSE);
 330   g_return_val_if_fail (name != NULL, FALSE);
 331
 332   structure_name = g_quark_to_string (structure->name);
 333
 334   return (structure_name && strcmp (structure_name, name) == 0);
 335 }
 336
 337 /**
 338  * gst_structure_get_name_id:
 339  * @structure: a #GstStructure
 340  *
 341  * Get the name of @structure as a GQuark.
 342  *
 343  * Returns: the quark representing the name of the structure.
 344  */
 345 GQuark
 346 gst_structure_get_name_id (const GstStructure * structure)
 347 {
 348   g_return_val_if_fail (structure != NULL, 0);
 349
 350   return structure->name;
 351 }
 352
 353 /**
 354  * gst_structure_set_name:
 355  * @structure: a #GstStructure
 356  * @name: the new name of the structure
 357  *
 358  * Sets the name of the structure to the given name.  The string
 359  * provided is copied before being used.
 360  */
 361 void
 362 gst_structure_set_name (GstStructure * structure, const gchar * name)
 363 {
 364   g_return_if_fail (structure != NULL);
 365   g_return_if_fail (name != NULL);
 366   g_return_if_fail (IS_MUTABLE (structure));
 367
 368   structure->name = g_quark_from_string (name);
 369 }
 370
 371 /**
 372  * gst_structure_id_set_value:
 373  * @structure: a #GstStructure
 374  * @field: a #GQuark representing a field
 375  * @value: the new value of the field
 376  *
 377  * Sets the field with the given GQuark @field to @value.  If the field
 378  * does not exist, it is created.  If the field exists, the previous
 379  * value is replaced and freed.
 380  */
 381 void
 382 gst_structure_id_set_value (GstStructure * structure,
 383     GQuark field, const GValue * value)
 384 {
 385   GstStructureField gsfield = { 0, {0,} };
 386
 387   g_return_if_fail (structure != NULL);
 388   g_return_if_fail (G_IS_VALUE (value));
 389   g_return_if_fail (IS_MUTABLE (structure));
 390
 391   gsfield.name = field;
 392   gst_value_init_and_copy (&gsfield.value, value);
 393
 394   gst_structure_set_field (structure, &gsfield);
 395 }
 396
 397 /**
 398  * gst_structure_set_value:
 399  * @structure: a #GstStructure
 400  * @fieldname: the name of the field to set
 401  * @value: the new value of the field
 402  *
 403  * Sets the field with the given name @field to @value.  If the field
 404  * does not exist, it is created.  If the field exists, the previous
 405  * value is replaced and freed.
 406  */
 407 void
 408 gst_structure_set_value (GstStructure * structure,
 409     const gchar * fieldname, const GValue * value)
 410 {
 411   g_return_if_fail (structure != NULL);
 412   g_return_if_fail (fieldname != NULL);
 413   g_return_if_fail (G_IS_VALUE (value));
 414   g_return_if_fail (IS_MUTABLE (structure));
 415
 416   gst_structure_id_set_value (structure, g_quark_from_string (fieldname),
 417       value);
 418 }
 419
 420 /**
 421  * gst_structure_set:
 422  * @structure: a #GstStructure
 423  * @fieldname: the name of the field to set
 424  * @...: variable arguments
 425  *
 426  * Parses the variable arguments and sets fields accordingly.
 427  * Variable arguments should be in the form field name, field type
 428  * (as a GType), value(s).  The last variable argument should be NULL.
 429  */
 430 void
 431 gst_structure_set (GstStructure * structure, const gchar * field, ...)
 432 {
 433   va_list varargs;
 434
 435   g_return_if_fail (structure != NULL);
 436
 437   va_start (varargs, field);
 438
 439   gst_structure_set_valist (structure, field, varargs);
 440
 441   va_end (varargs);
 442 }
 443
 444 /**
 445  * gst_structure_set_valist:
 446  * @structure: a #GstStructure
 447  * @fieldname: the name of the field to set
 448  * @varargs: variable arguments
 449  *
 450  * va_list form of gst_structure_set().
 451  */
 452 void
 453 gst_structure_set_valist (GstStructure * structure,
 454     const gchar * fieldname, va_list varargs)
 455 {
 456   gchar *err = NULL;
 457   GType type;
 458
 459   g_return_if_fail (structure != NULL);
 460   g_return_if_fail (IS_MUTABLE (structure));
 461
 462   while (fieldname) {
 463     GstStructureField field = { 0 };
 464
 465     field.name = g_quark_from_string (fieldname);
 466
 467     type = va_arg (varargs, GType);
 468
 469 #if GLIB_CHECK_VERSION(2,8,0)
 470     if (type == G_TYPE_DATE) {
 471       g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
 472       type = GST_TYPE_DATE;
 473     }
 474 #endif
 475
 476     g_value_init (&field.value, type);
 477     G_VALUE_COLLECT (&field.value, varargs, 0, &err);
 478     if (err) {
 479       g_critical ("%s", err);
 480       return;
 481     }
 482     gst_structure_set_field (structure, &field);
 483
 484     fieldname = va_arg (varargs, gchar *);
 485   }
 486 }
 487
 488 /* If the structure currently contains a field with the same name, it is
 489  * replaced with the provided field. Otherwise, the field is added to the
 490  * structure. The field's value is not deeply copied.
 491  */
 492 static void
 493 gst_structure_set_field (GstStructure * structure, GstStructureField * field)
 494 {
 495   GstStructureField *f;
 496   guint i;
 497
 498   for (i = 0; i < structure->fields->len; i++) {
 499     f = GST_STRUCTURE_FIELD (structure, i);
 500
 501     if (f->name == field->name) {
 502       g_value_unset (&f->value);
 503       memcpy (f, field, sizeof (GstStructureField));
 504       return;
 505     }
 506   }
 507
 508   g_array_append_val (structure->fields, *field);
 509 }
 510
 511 /* If there is no field with the given ID, NULL is returned.
 512  */
 513 static GstStructureField *
 514 gst_structure_id_get_field (const GstStructure * structure, GQuark field_id)
 515 {
 516   GstStructureField *field;
 517   guint i;
 518
 519   g_return_val_if_fail (structure != NULL, NULL);
 520
 521   for (i = 0; i < structure->fields->len; i++) {
 522     field = GST_STRUCTURE_FIELD (structure, i);
 523
 524     if (field->name == field_id)
 525       return field;
 526   }
 527
 528   return NULL;
 529 }
 530
 531 /* If there is no field with the given ID, NULL is returned.
 532  */
 533 static GstStructureField *
 534 gst_structure_get_field (const GstStructure * structure,
 535     const gchar * fieldname)
 536 {
 537   g_return_val_if_fail (structure != NULL, NULL);
 538   g_return_val_if_fail (fieldname != NULL, NULL);
 539
 540   return gst_structure_id_get_field (structure,
 541       g_quark_from_string (fieldname));
 542 }
 543
 544 /**
 545  * gst_structure_get_value:
 546  * @structure: a #GstStructure
 547  * @fieldname: the name of the field to get
 548  *
 549  * Get the value of the field with name @fieldname.
 550  *
 551  * Returns: the #GValue corresponding to the field with the given name.
 552  */
 553 const GValue *
 554 gst_structure_get_value (const GstStructure * structure,
 555     const gchar * fieldname)
 556 {
 557   GstStructureField *field;
 558
 559   g_return_val_if_fail (structure != NULL, NULL);
 560   g_return_val_if_fail (fieldname != NULL, NULL);
 561
 562   field = gst_structure_get_field (structure, fieldname);
 563   if (field == NULL)
 564     return NULL;
 565
 566   return &field->value;
 567 }
 568
 569 /**
 570  * gst_structure_id_get_value:
 571  * @structure: a #GstStructure
 572  * @field: the #GQuark of the field to get
 573  *
 574  * Get the value of the field with GQuark @field.
 575  *
 576  * Returns: the #GValue corresponding to the field with the given name
 577  *          identifier.
 578  */
 579 const GValue *
 580 gst_structure_id_get_value (const GstStructure * structure, GQuark field)
 581 {
 582   GstStructureField *gsfield;
 583
 584   g_return_val_if_fail (structure != NULL, NULL);
 585
 586   gsfield = gst_structure_id_get_field (structure, field);
 587   if (gsfield == NULL)
 588     return NULL;
 589
 590   return &gsfield->value;
 591 }
 592
 593 /**
 594  * gst_structure_remove_field:
 595  * @structure: a #GstStructure
 596  * @fieldname: the name of the field to remove
 597  *
 598  * Removes the field with the given name.  If the field with the given
 599  * name does not exist, the structure is unchanged.
 600  */
 601 void
 602 gst_structure_remove_field (GstStructure * structure, const gchar * fieldname)
 603 {
 604   GstStructureField *field;
 605   GQuark id;
 606   guint i;
 607
 608   g_return_if_fail (structure != NULL);
 609   g_return_if_fail (fieldname != NULL);
 610   g_return_if_fail (IS_MUTABLE (structure));
 611
 612   id = g_quark_from_string (fieldname);
 613
 614   for (i = 0; i < structure->fields->len; i++) {
 615     field = GST_STRUCTURE_FIELD (structure, i);
 616
 617     if (field->name == id) {
 618       if (G_IS_VALUE (&field->value)) {
 619         g_value_unset (&field->value);
 620       }
 621       structure->fields = g_array_remove_index (structure->fields, i);
 622       return;
 623     }
 624   }
 625 }
 626
 627 /**
 628  * gst_structure_remove_fields:
 629  * @structure: a #GstStructure
 630  * @fieldname: the name of the field to remove
 631  * @...: NULL-terminated list of more fieldnames to remove
 632  *
 633  * Removes the fields with the given names. If a field does not exist, the
 634  * argument is ignored.
 635  */
 636 void
 637 gst_structure_remove_fields (GstStructure * structure,
 638     const gchar * fieldname, ...)
 639 {
 640   va_list varargs;
 641
 642   g_return_if_fail (structure != NULL);
 643   g_return_if_fail (fieldname != NULL);
 644   /* mutability checked in remove_field */
 645
 646   va_start (varargs, fieldname);
 647
 648   gst_structure_remove_fields_valist (structure, fieldname, varargs);
 649
 650   va_end (varargs);
 651 }
 652
 653 /**
 654  * gst_structure_remove_fields_valist:
 655  * @structure: a #GstStructure
 656  * @fieldname: the name of the field to remove
 657  * @varargs: NULL-terminated list of more fieldnames to remove
 658  *
 659  * va_list form of gst_structure_remove_fields().
 660  */
 661 void
 662 gst_structure_remove_fields_valist (GstStructure * structure,
 663     const gchar * fieldname, va_list varargs)
 664 {
 665   gchar *field = (gchar *) fieldname;
 666
 667   g_return_if_fail (structure != NULL);
 668   g_return_if_fail (fieldname != NULL);
 669   /* mutability checked in remove_field */
 670
 671   while (field) {
 672     gst_structure_remove_field (structure, field);
 673     field = va_arg (varargs, char *);
 674   }
 675 }
 676
 677 /**
 678  * gst_structure_remove_all_fields:
 679  * @structure: a #GstStructure
 680  *
 681  * Removes all fields in a GstStructure.
 682  */
 683 void
 684 gst_structure_remove_all_fields (GstStructure * structure)
 685 {
 686   GstStructureField *field;
 687   int i;
 688
 689   g_return_if_fail (structure != NULL);
 690   g_return_if_fail (IS_MUTABLE (structure));
 691
 692   for (i = structure->fields->len - 1; i >= 0; i--) {
 693     field = GST_STRUCTURE_FIELD (structure, i);
 694
 695     if (G_IS_VALUE (&field->value)) {
 696       g_value_unset (&field->value);
 697     }
 698     structure->fields = g_array_remove_index (structure->fields, i);
 699   }
 700 }
 701
 702 /**
 703  * gst_structure_get_field_type:
 704  * @structure: a #GstStructure
 705  * @fieldname: the name of the field
 706  *
 707  * Finds the field with the given name, and returns the type of the
 708  * value it contains.  If the field is not found, G_TYPE_INVALID is
 709  * returned.
 710  *
 711  * Returns: the #GValue of the field
 712  */
 713 GType
 714 gst_structure_get_field_type (const GstStructure * structure,
 715     const gchar * fieldname)
 716 {
 717   GstStructureField *field;
 718
 719   g_return_val_if_fail (structure != NULL, G_TYPE_INVALID);
 720   g_return_val_if_fail (fieldname != NULL, G_TYPE_INVALID);
 721
 722   field = gst_structure_get_field (structure, fieldname);
 723   if (field == NULL)
 724     return G_TYPE_INVALID;
 725
 726   return G_VALUE_TYPE (&field->value);
 727 }
 728
 729 /**
 730  * gst_structure_n_fields:
 731  * @structure: a #GstStructure
 732  *
 733  * Get the number of fields in the structure.
 734  *
 735  * Returns: the number of fields in the structure
 736  */
 737 gint
 738 gst_structure_n_fields (const GstStructure * structure)
 739 {
 740   g_return_val_if_fail (structure != NULL, 0);
 741
 742   return structure->fields->len;
 743 }
 744
 745 /**
 746  * gst_structure_nth_field_name:
 747  * @structure: a #GstStructure
 748  * @index: the index to get the name of
 749  *
 750  * Get the name of the given field number, counting from 0 onwards.
 751  *
 752  * Returns: the name of the given field number
 753  */
 754 const gchar *
 755 gst_structure_nth_field_name (const GstStructure * structure, guint index)
 756 {
 757   GstStructureField *field;
 758
 759   field = GST_STRUCTURE_FIELD (structure, index);
 760   return g_quark_to_string (field->name);
 761 }
 762
 763 /**
 764  * gst_structure_foreach:
 765  * @structure: a #GstStructure
 766  * @func: a function to call for each field
 767  * @user_data: private data
 768  *
 769  * Calls the provided function once for each field in the #GstStructure. The
 770  * function must not modify the fields. Also see gst_structure_map_in_place().
 771  *
 772  * Returns: TRUE if the supplied function returns TRUE For each of the fields,
 773  * FALSE otherwise.
 774  */
 775 gboolean
 776 gst_structure_foreach (const GstStructure * structure,
 777     GstStructureForeachFunc func, gpointer user_data)
 778 {
 779   guint i;
 780   GstStructureField *field;
 781   gboolean ret;
 782
 783   g_return_val_if_fail (structure != NULL, FALSE);
 784
 785   for (i = 0; i < structure->fields->len; i++) {
 786     field = GST_STRUCTURE_FIELD (structure, i);
 787
 788     ret = func (field->name, &field->value, user_data);
 789     if (!ret)
 790       return FALSE;
 791   }
 792
 793   return TRUE;
 794 }
 795
 796 /**
 797  * gst_structure_map_in_place:
 798  * @structure: a #GstStructure
 799  * @func: a function to call for each field
 800  * @user_data: private data
 801  *
 802  * Calls the provided function once for each field in the #GstStructure. In
 803  * contrast to gst_structure_foreach(), the function may modify the fields. The
 804  * structure must be mutable.
 805  *
 806  * Returns: TRUE if the supplied function returns TRUE For each of the fields,
 807  * FALSE otherwise.
 808  */
 809 gboolean
 810 gst_structure_map_in_place (GstStructure * structure,
 811     GstStructureMapFunc func, gpointer user_data)
 812 {
 813   guint i;
 814   GstStructureField *field;
 815   gboolean ret;
 816
 817   g_return_val_if_fail (structure != NULL, FALSE);
 818   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
 819
 820   for (i = 0; i < structure->fields->len; i++) {
 821     field = GST_STRUCTURE_FIELD (structure, i);
 822
 823     ret = func (field->name, &field->value, user_data);
 824     if (!ret)
 825       return FALSE;
 826   }
 827
 828   return TRUE;
 829 }
 830
 831 /**
 832  * gst_structure_has_field:
 833  * @structure: a #GstStructure
 834  * @fieldname: the name of a field
 835  *
 836  * Check if @structure contains a field named @fieldname.
 837  *
 838  * Returns: TRUE if the structure contains a field with the given name
 839  */
 840 gboolean
 841 gst_structure_has_field (const GstStructure * structure,
 842     const gchar * fieldname)
 843 {
 844   GstStructureField *field;
 845
 846   g_return_val_if_fail (structure != NULL, 0);
 847   g_return_val_if_fail (fieldname != NULL, 0);
 848
 849   field = gst_structure_get_field (structure, fieldname);
 850
 851   return (field != NULL);
 852 }
 853
 854 /**
 855  * gst_structure_has_field_typed:
 856  * @structure: a #GstStructure
 857  * @fieldname: the name of a field
 858  * @type: the type of a value
 859  *
 860  * Check if @structure contains a field named @fieldname and with GType @type.
 861  *
 862  * Returns: TRUE if the structure contains a field with the given name and type
 863  */
 864 gboolean
 865 gst_structure_has_field_typed (const GstStructure * structure,
 866     const gchar * fieldname, GType type)
 867 {
 868   GstStructureField *field;
 869
 870   g_return_val_if_fail (structure != NULL, 0);
 871   g_return_val_if_fail (fieldname != NULL, 0);
 872
 873   field = gst_structure_get_field (structure, fieldname);
 874   if (field == NULL)
 875     return FALSE;
 876
 877   return (G_VALUE_TYPE (&field->value) == type);
 878 }
 879
 880
 881 /* utility functions */
 882
 883 /**
 884  * gst_structure_get_boolean:
 885  * @structure: a #GstStructure
 886  * @fieldname: the name of a field
 887  * @value: a pointer to a #gboolean to set
 888  *
 889  * Sets the boolean pointed to by @value corresponding to the value of the
 890  * given field.  Caller is responsible for making sure the field exists
 891  * and has the correct type.
 892  *
 893  * Returns: TRUE if the value could be set correctly. If there was no field
 894  * with @fieldname or the existing field did not contain a boolean, this function
 895  * returns FALSE.
 896  */
 897 gboolean
 898 gst_structure_get_boolean (const GstStructure * structure,
 899     const gchar * fieldname, gboolean * value)
 900 {
 901   GstStructureField *field;
 902
 903   g_return_val_if_fail (structure != NULL, FALSE);
 904   g_return_val_if_fail (fieldname != NULL, FALSE);
 905
 906   field = gst_structure_get_field (structure, fieldname);
 907
 908   if (field == NULL)
 909     return FALSE;
 910   if (!G_VALUE_HOLDS_BOOLEAN (&field->value))
 911     return FALSE;
 912
 913   *value = g_value_get_boolean (&field->value);
 914
 915   return TRUE;
 916 }
 917
 918 /**
 919  * gst_structure_get_int:
 920  * @structure: a #GstStructure
 921  * @fieldname: the name of a field
 922  * @value: a pointer to an int to set
 923  *
 924  * Sets the int pointed to by @value corresponding to the value of the
 925  * given field.  Caller is responsible for making sure the field exists
 926  * and has the correct type.
 927  *
 928  * Returns: TRUE if the value could be set correctly. If there was no field
 929  * with @fieldname or the existing field did not contain an int, this function
 930  * returns FALSE.
 931  */
 932 gboolean
 933 gst_structure_get_int (const GstStructure * structure,
 934     const gchar * fieldname, gint * value)
 935 {
 936   GstStructureField *field;
 937
 938   g_return_val_if_fail (structure != NULL, FALSE);
 939   g_return_val_if_fail (fieldname != NULL, FALSE);
 940   g_return_val_if_fail (value != NULL, FALSE);
 941
 942   field = gst_structure_get_field (structure, fieldname);
 943
 944   if (field == NULL)
 945     return FALSE;
 946   if (!G_VALUE_HOLDS_INT (&field->value))
 947     return FALSE;
 948
 949   *value = g_value_get_int (&field->value);
 950
 951   return TRUE;
 952 }
 953
 954 /**
 955  * gst_structure_get_fourcc:
 956  * @structure: a #GstStructure
 957  * @fieldname: the name of a field
 958  * @value: a pointer to a #GstFourcc to set
 959  *
 960  * Sets the #GstFourcc pointed to by @value corresponding to the value of the
 961  * given field.  Caller is responsible for making sure the field exists
 962  * and has the correct type.
 963  *
 964  * Returns: TRUE if the value could be set correctly. If there was no field
 965  * with @fieldname or the existing field did not contain a fourcc, this function
 966  * returns FALSE.
 967  */
 968 gboolean
 969 gst_structure_get_fourcc (const GstStructure * structure,
 970     const gchar * fieldname, guint32 * value)
 971 {
 972   GstStructureField *field;
 973
 974   g_return_val_if_fail (structure != NULL, FALSE);
 975   g_return_val_if_fail (fieldname != NULL, FALSE);
 976   g_return_val_if_fail (value != NULL, FALSE);
 977
 978   field = gst_structure_get_field (structure, fieldname);
 979
 980   if (field == NULL)
 981     return FALSE;
 982   if (!GST_VALUE_HOLDS_FOURCC (&field->value))
 983     return FALSE;
 984
 985   *value = gst_value_get_fourcc (&field->value);
 986
 987   return TRUE;
 988 }
 989
 990 /**
 991  * gst_structure_get_date:
 992  * @structure: a #GstStructure
 993  * @fieldname: the name of a field
 994  * @value: a pointer to a #GDate to set
 995  *
 996  * Sets the date pointed to by @value corresponding to the date of the
 997  * given field.  Caller is responsible for making sure the field exists
 998  * and has the correct type.
 999  *
1000  * Returns: TRUE if the value could be set correctly. If there was no field
1001  * with @fieldname or the existing field did not contain a data, this function
1002  * returns FALSE.
1003  */
1004 gboolean
1005 gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
1006     GDate ** value)
1007 {
1008   GstStructureField *field;
1009
1010   g_return_val_if_fail (structure != NULL, FALSE);
1011   g_return_val_if_fail (fieldname != NULL, FALSE);
1012   g_return_val_if_fail (value != NULL, FALSE);
1013
1014   field = gst_structure_get_field (structure, fieldname);
1015
1016   if (field == NULL)
1017     return FALSE;
1018   if (!GST_VALUE_HOLDS_DATE (&field->value))
1019     return FALSE;
1020
1021   *value = g_value_dup_boxed (&field->value);
1022
1023   return TRUE;
1024 }
1025
1026 /**
1027  * gst_structure_get_clock_time:
1028  * @structure: a #GstStructure
1029  * @fieldname: the name of a field
1030  * @value: a pointer to a #GstClockTime to set
1031  *
1032  * Sets the clock time pointed to by @value corresponding to the clock time
1033  * of the given field.  Caller is responsible for making sure the field exists
1034  * and has the correct type.
1035  *
1036  * Returns: TRUE if the value could be set correctly. If there was no field
1037  * with @fieldname or the existing field did not contain a #GstClockTime, this
1038  * function returns FALSE.
1039  */
1040 gboolean
1041 gst_structure_get_clock_time (const GstStructure * structure,
1042     const gchar * fieldname, GstClockTime * value)
1043 {
1044   GstStructureField *field;
1045
1046   g_return_val_if_fail (structure != NULL, FALSE);
1047   g_return_val_if_fail (fieldname != NULL, FALSE);
1048   g_return_val_if_fail (value != NULL, FALSE);
1049
1050   field = gst_structure_get_field (structure, fieldname);
1051
1052   if (field == NULL)
1053     return FALSE;
1054   if (!G_VALUE_HOLDS_UINT64 (&field->value))
1055     return FALSE;
1056
1057   *value = g_value_get_uint64 (&field->value);
1058
1059   return TRUE;
1060 }
1061
1062 /**
1063  * gst_structure_get_double:
1064  * @structure: a #GstStructure
1065  * @fieldname: the name of a field
1066  * @value: a pointer to a #GstFourcc to set
1067  *
1068  * Sets the double pointed to by @value corresponding to the value of the
1069  * given field.  Caller is responsible for making sure the field exists
1070  * and has the correct type.
1071  *
1072  * Returns: TRUE if the value could be set correctly. If there was no field
1073  * with @fieldname or the existing field did not contain a double, this
1074  * function returns FALSE.
1075  */
1076 gboolean
1077 gst_structure_get_double (const GstStructure * structure,
1078     const gchar * fieldname, gdouble * value)
1079 {
1080   GstStructureField *field;
1081
1082   g_return_val_if_fail (structure != NULL, FALSE);
1083   g_return_val_if_fail (fieldname != NULL, FALSE);
1084   g_return_val_if_fail (value != NULL, FALSE);
1085
1086   field = gst_structure_get_field (structure, fieldname);
1087
1088   if (field == NULL)
1089     return FALSE;
1090   if (!G_VALUE_HOLDS_DOUBLE (&field->value))
1091     return FALSE;
1092
1093   *value = g_value_get_double (&field->value);
1094
1095   return TRUE;
1096 }
1097
1098 /**
1099  * gst_structure_get_string:
1100  * @structure: a #GstStructure
1101  * @fieldname: the name of a field
1102  *
1103  * Finds the field corresponding to @fieldname, and returns the string
1104  * contained in the field's value.  Caller is responsible for making
1105  * sure the field exists and has the correct type.
1106  *
1107  * The string should not be modified, and remains valid until the next
1108  * call to a gst_structure_*() function with the given structure.
1109  *
1110  * Returns: a pointer to the string or NULL when the field did not exist
1111  * or did not contain a string.
1112  */
1113 const gchar *
1114 gst_structure_get_string (const GstStructure * structure,
1115     const gchar * fieldname)
1116 {
1117   GstStructureField *field;
1118
1119   g_return_val_if_fail (structure != NULL, NULL);
1120   g_return_val_if_fail (fieldname != NULL, NULL);
1121
1122   field = gst_structure_get_field (structure, fieldname);
1123
1124   if (field == NULL)
1125     return NULL;
1126   if (!G_VALUE_HOLDS_STRING (&field->value))
1127     return NULL;
1128
1129   return g_value_get_string (&field->value);
1130 }
1131
1132 /**
1133  * gst_structure_get_enum:
1134  * @structure: a #GstStructure
1135  * @fieldname: the name of a field
1136  * @enumtype: the enum type of a field
1137  * @value: a pointer to an int to set
1138  *
1139  * Sets the int pointed to by @value corresponding to the value of the
1140  * given field.  Caller is responsible for making sure the field exists,
1141  * has the correct type and that the enumtype is correct.
1142  *
1143  * Returns: TRUE if the value could be set correctly. If there was no field
1144  * with @fieldname or the existing field did not contain an enum of the given
1145  * type, this function returns FALSE.
1146  */
1147 gboolean
1148 gst_structure_get_enum (const GstStructure * structure,
1149     const gchar * fieldname, GType enumtype, gint * value)
1150 {
1151   GstStructureField *field;
1152
1153   g_return_val_if_fail (structure != NULL, FALSE);
1154   g_return_val_if_fail (fieldname != NULL, FALSE);
1155   g_return_val_if_fail (enumtype != G_TYPE_INVALID, FALSE);
1156   g_return_val_if_fail (value != NULL, FALSE);
1157
1158   field = gst_structure_get_field (structure, fieldname);
1159
1160   if (field == NULL)
1161     return FALSE;
1162   if (!G_VALUE_HOLDS_ENUM (&field->value))
1163     return FALSE;
1164   if (!G_TYPE_CHECK_VALUE_TYPE (&field->value, enumtype))
1165     return FALSE;
1166
1167   *value = g_value_get_enum (&field->value);
1168
1169   return TRUE;
1170 }
1171
1172 /**
1173  * gst_structure_get_fraction:
1174  * @structure: a #GstStructure
1175  * @fieldname: the name of a field
1176  * @value_numerator: a pointer to an int to set
1177  * @value_denominator: a pointer to an int to set
1178  *
1179  * Sets the integers pointed to by @value_numerator and @value_denominator
1180  * corresponding to the value of the given field.  Caller is responsible
1181  * for making sure the field exists and has the correct type.
1182  *
1183  * Returns: TRUE if the values could be set correctly. If there was no field
1184  * with @fieldname or the existing field did not contain a GstFraction, this
1185  * function returns FALSE.
1186  */
1187 gboolean
1188 gst_structure_get_fraction (const GstStructure * structure,
1189     const gchar * fieldname, gint * value_numerator, gint * value_denominator)
1190 {
1191   GstStructureField *field;
1192
1193   g_return_val_if_fail (structure != NULL, FALSE);
1194   g_return_val_if_fail (fieldname != NULL, FALSE);
1195   g_return_val_if_fail (value_numerator != NULL, FALSE);
1196   g_return_val_if_fail (value_denominator != NULL, FALSE);
1197
1198   field = gst_structure_get_field (structure, fieldname);
1199
1200   if (field == NULL)
1201     return FALSE;
1202   if (!GST_VALUE_HOLDS_FRACTION (&field->value))
1203     return FALSE;
1204
1205   *value_numerator = gst_value_get_fraction_numerator (&field->value);
1206   *value_denominator = gst_value_get_fraction_denominator (&field->value);
1207
1208   return TRUE;
1209 }
1210
1211 typedef struct _GstStructureAbbreviation
1212 {
1213   char *type_name;
1214   GType type;
1215 }
1216 GstStructureAbbreviation;
1217
1218 static GstStructureAbbreviation *
1219 gst_structure_get_abbrs (gint * n_abbrs)
1220 {
1221   static GstStructureAbbreviation *abbrs = NULL;
1222   static gint num = 0;
1223
1224   if (abbrs == NULL) {
1225     /* dynamically generate the array */
1226     GstStructureAbbreviation dyn_abbrs[] = {
1227       {"int", G_TYPE_INT}
1228       ,
1229       {"i", G_TYPE_INT}
1230       ,
1231       {"float", G_TYPE_FLOAT}
1232       ,
1233       {"f", G_TYPE_FLOAT}
1234       ,
1235       {"double", G_TYPE_DOUBLE}
1236       ,
1237       {"d", G_TYPE_DOUBLE}
1238       ,
1239       {"buffer", GST_TYPE_BUFFER}
1240       ,
1241       {"fourcc", GST_TYPE_FOURCC}
1242       ,
1243       {"4", GST_TYPE_FOURCC}
1244       ,
1245       {"fraction", GST_TYPE_FRACTION}
1246       ,
1247       {"boolean", G_TYPE_BOOLEAN}
1248       ,
1249       {"bool", G_TYPE_BOOLEAN}
1250       ,
1251       {"b", G_TYPE_BOOLEAN}
1252       ,
1253       {"string", G_TYPE_STRING}
1254       ,
1255       {"str", G_TYPE_STRING}
1256       ,
1257       {"s", G_TYPE_STRING}
1258     };
1259     num = G_N_ELEMENTS (dyn_abbrs);
1260     /* permanently allocate and copy the array now */
1261     abbrs = g_new0 (GstStructureAbbreviation, num);
1262     memcpy (abbrs, dyn_abbrs, sizeof (GstStructureAbbreviation) * num);
1263   }
1264   *n_abbrs = num;
1265
1266   return abbrs;
1267 }
1268
1269 static GType
1270 gst_structure_from_abbr (const char *type_name)
1271 {
1272   int i;
1273   GstStructureAbbreviation *abbrs;
1274   gint n_abbrs;
1275
1276   g_return_val_if_fail (type_name != NULL, G_TYPE_INVALID);
1277
1278   abbrs = gst_structure_get_abbrs (&n_abbrs);
1279
1280   for (i = 0; i < n_abbrs; i++) {
1281     if (strcmp (type_name, abbrs[i].type_name) == 0) {
1282       return abbrs[i].type;
1283     }
1284   }
1285
1286   /* this is the fallback */
1287   return g_type_from_name (type_name);
1288 }
1289
1290 static const char *
1291 gst_structure_to_abbr (GType type)
1292 {
1293   int i;
1294   GstStructureAbbreviation *abbrs;
1295   gint n_abbrs;
1296
1297   g_return_val_if_fail (type != G_TYPE_INVALID, NULL);
1298
1299   abbrs = gst_structure_get_abbrs (&n_abbrs);
1300
1301   for (i = 0; i < n_abbrs; i++) {
1302     if (type == abbrs[i].type) {
1303       return abbrs[i].type_name;
1304     }
1305   }
1306
1307   return g_type_name (type);
1308 }
1309
1310 static GType
1311 gst_structure_value_get_generic_type (GValue * val)
1312 {
1313   if (G_VALUE_TYPE (val) == GST_TYPE_LIST
1314       || G_VALUE_TYPE (val) == GST_TYPE_ARRAY) {
1315     GArray *array = g_value_peek_pointer (val);
1316
1317     if (array->len > 0) {
1318       GValue *value = &g_array_index (array, GValue, 0);
1319
1320       return gst_structure_value_get_generic_type (value);
1321     } else {
1322       return G_TYPE_INT;
1323     }
1324   } else if (G_VALUE_TYPE (val) == GST_TYPE_INT_RANGE) {
1325     return G_TYPE_INT;
1326   } else if (G_VALUE_TYPE (val) == GST_TYPE_DOUBLE_RANGE) {
1327     return G_TYPE_DOUBLE;
1328   } else if (G_VALUE_TYPE (val) == GST_TYPE_FRACTION_RANGE) {
1329     return GST_TYPE_FRACTION;
1330   }
1331   return G_VALUE_TYPE (val);
1332 }
1333
1334 #define GST_ASCII_IS_STRING(c) (g_ascii_isalnum((c)) || ((c) == '_') || \
1335       ((c) == '-') || ((c) == '+') || ((c) == '/') || ((c) == ':') || \
1336       ((c) == '.'))
1337
1338 /**
1339  * gst_structure_to_string:
1340  * @structure: a #GstStructure
1341  *
1342  * Converts @structure to a human-readable string representation.
1343  *
1344  * Returns: a pointer to string allocated by g_malloc(). g_free() after
1345  * usage.
1346  */
1347 gchar *
1348 gst_structure_to_string (const GstStructure * structure)
1349 {
1350   GstStructureField *field;
1351   GString *s;
1352   guint i;
1353
1354   /* NOTE:  This function is potentially called by the debug system,
1355    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1356    * should be careful to avoid recursion.  This includes any functions
1357    * called by gst_structure_to_string.  In particular, calls should
1358    * not use the GST_PTR_FORMAT extension.  */
1359
1360   g_return_val_if_fail (structure != NULL, NULL);
1361
1362   s = g_string_new ("");
1363   /* FIXME this string may need to be escaped */
1364   g_string_append_printf (s, "%s", g_quark_to_string (structure->name));
1365   for (i = 0; i < structure->fields->len; i++) {
1366     char *t;
1367     GType type;
1368
1369     field = GST_STRUCTURE_FIELD (structure, i);
1370
1371     t = gst_value_serialize (&field->value);
1372     type = gst_structure_value_get_generic_type (&field->value);
1373
1374     g_string_append_printf (s, ", %s=(%s)%s", g_quark_to_string (field->name),
1375         gst_structure_to_abbr (type), GST_STR_NULL (t));
1376     g_free (t);
1377   }
1378   return g_string_free (s, FALSE);
1379 }
1380
1381 /*
1382  * r will still point to the string. if end == next, the string will not be
1383  * null-terminated. In all other cases it will be.
1384  * end = pointer to char behind end of string, next = pointer to start of
1385  * unread data.
1386  * THIS FUNCTION MODIFIES THE STRING AND DETECTS INSIDE A NONTERMINATED STRING
1387  */
1388 static gboolean
1389 gst_structure_parse_string (gchar * s, gchar ** end, gchar ** next)
1390 {
1391   gchar *w;
1392
1393   if (*s == 0)
1394     return FALSE;
1395
1396   if (*s != '"') {
1397     int ret;
1398
1399     ret = gst_structure_parse_simple_string (s, end);
1400     *next = *end;
1401
1402     return ret;
1403   }
1404
1405   w = s;
1406   s++;
1407   while (*s != '"') {
1408     if (*s == 0)
1409       return FALSE;
1410
1411     if (*s == '\\') {
1412       s++;
1413     }
1414
1415     *w = *s;
1416     w++;
1417     s++;
1418   }
1419   s++;
1420
1421   *end = w;
1422   *next = s;
1423
1424   return TRUE;
1425 }
1426
1427 static gboolean
1428 gst_structure_parse_range (gchar * s, gchar ** after, GValue * value,
1429     GType type)
1430 {
1431   GValue value1 = { 0 };
1432   GValue value2 = { 0 };
1433   GType range_type;
1434   gboolean ret;
1435
1436
1437   if (*s != '[')
1438     return FALSE;
1439   s++;
1440
1441   ret = gst_structure_parse_value (s, &s, &value1, type);
1442   if (ret == FALSE)
1443     return FALSE;
1444
1445   while (g_ascii_isspace (*s))
1446     s++;
1447
1448   if (*s != ',')
1449     return FALSE;
1450   s++;
1451
1452   while (g_ascii_isspace (*s))
1453     s++;
1454
1455   ret = gst_structure_parse_value (s, &s, &value2, type);
1456   if (ret == FALSE)
1457     return FALSE;
1458
1459   while (g_ascii_isspace (*s))
1460     s++;
1461
1462   if (*s != ']')
1463     return FALSE;
1464   s++;
1465
1466   if (G_VALUE_TYPE (&value1) != G_VALUE_TYPE (&value2))
1467     return FALSE;
1468
1469   if (G_VALUE_TYPE (&value1) == G_TYPE_DOUBLE) {
1470     range_type = GST_TYPE_DOUBLE_RANGE;
1471     g_value_init (value, range_type);
1472     gst_value_set_double_range (value, g_value_get_double (&value1),
1473         g_value_get_double (&value2));
1474   } else if (G_VALUE_TYPE (&value1) == G_TYPE_INT) {
1475     range_type = GST_TYPE_INT_RANGE;
1476     g_value_init (value, range_type);
1477     gst_value_set_int_range (value, g_value_get_int (&value1),
1478         g_value_get_int (&value2));
1479   } else if (G_VALUE_TYPE (&value1) == GST_TYPE_FRACTION) {
1480     range_type = GST_TYPE_FRACTION_RANGE;
1481     g_value_init (value, range_type);
1482     gst_value_set_fraction_range (value, &value1, &value2);
1483   } else {
1484     return FALSE;
1485   }
1486
1487   *after = s;
1488   return TRUE;
1489 }
1490
1491 static gboolean
1492 gst_structure_parse_any_list (gchar * s, gchar ** after, GValue * value,
1493     GType type, GType list_type, char begin, char end)
1494 {
1495   GValue list_value = { 0 };
1496   gboolean ret;
1497   GArray *array;
1498
1499   g_value_init (value, list_type);
1500   array = g_value_peek_pointer (value);
1501
1502   if (*s != begin)
1503     return FALSE;
1504   s++;
1505
1506   while (g_ascii_isspace (*s))
1507     s++;
1508   if (*s == end) {
1509     s++;
1510     *after = s;
1511     return TRUE;
1512   }
1513
1514   ret = gst_structure_parse_value (s, &s, &list_value, type);
1515   if (ret == FALSE)
1516     return FALSE;
1517
1518   g_array_append_val (array, list_value);
1519
1520   while (g_ascii_isspace (*s))
1521     s++;
1522
1523   while (*s != end) {
1524     if (*s != ',')
1525       return FALSE;
1526     s++;
1527
1528     while (g_ascii_isspace (*s))
1529       s++;
1530
1531     memset (&list_value, 0, sizeof (list_value));
1532     ret = gst_structure_parse_value (s, &s, &list_value, type);
1533     if (ret == FALSE)
1534       return FALSE;
1535
1536     g_array_append_val (array, list_value);
1537     while (g_ascii_isspace (*s))
1538       s++;
1539   }
1540
1541   s++;
1542
1543   *after = s;
1544   return TRUE;
1545 }
1546
1547 static gboolean
1548 gst_structure_parse_list (gchar * s, gchar ** after, GValue * value, GType type)
1549 {
1550   return gst_structure_parse_any_list (s, after, value, type, GST_TYPE_LIST,
1551       '{', '}');
1552 }
1553
1554 static gboolean
1555 gst_structure_parse_array (gchar * s, gchar ** after, GValue * value,
1556     GType type)
1557 {
1558   return gst_structure_parse_any_list (s, after, value, type,
1559       GST_TYPE_ARRAY, '<', '>');
1560 }
1561
1562 static gboolean
1563 gst_structure_parse_simple_string (gchar * str, gchar ** end)
1564 {
1565   char *s = str;
1566
1567   while (GST_ASCII_IS_STRING (*s)) {
1568     s++;
1569   }
1570
1571   *end = s;
1572
1573   return (s != str);
1574 }
1575
1576 static gboolean
1577 gst_structure_parse_field (gchar * str,
1578     gchar ** after, GstStructureField * field)
1579 {
1580   gchar *name;
1581   gchar *name_end;
1582   gchar *s;
1583   gchar c;
1584
1585   s = str;
1586
1587   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
1588     s++;
1589   name = s;
1590   if (!gst_structure_parse_simple_string (s, &name_end))
1591     return FALSE;
1592
1593   s = name_end;
1594   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
1595     s++;
1596
1597   if (*s != '=')
1598     return FALSE;
1599   s++;
1600
1601   c = *name_end;
1602   *name_end = 0;
1603   field->name = g_quark_from_string (name);
1604   *name_end = c;
1605
1606   if (!gst_structure_parse_value (s, &s, &field->value, G_TYPE_INVALID))
1607     return FALSE;
1608
1609   *after = s;
1610   return TRUE;
1611 }
1612
1613 static gboolean
1614 gst_structure_parse_value (gchar * str,
1615     gchar ** after, GValue * value, GType default_type)
1616 {
1617   gchar *type_name;
1618   gchar *type_end;
1619   gchar *value_s;
1620   gchar *value_end;
1621   gchar *s;
1622   gchar c;
1623   int ret = 0;
1624   GType type = default_type;
1625
1626
1627   s = str;
1628   while (g_ascii_isspace (*s))
1629     s++;
1630
1631   type_name = NULL;
1632   if (*s == '(') {
1633     type = G_TYPE_INVALID;
1634
1635     s++;
1636     while (g_ascii_isspace (*s))
1637       s++;
1638     type_name = s;
1639     if (!gst_structure_parse_simple_string (s, &type_end))
1640       return FALSE;
1641     s = type_end;
1642     while (g_ascii_isspace (*s))
1643       s++;
1644     if (*s != ')')
1645       return FALSE;
1646     s++;
1647     while (g_ascii_isspace (*s))
1648       s++;
1649
1650     c = *type_end;
1651     *type_end = 0;
1652     type = gst_structure_from_abbr (type_name);
1653     *type_end = c;
1654
1655     if (type == G_TYPE_INVALID)
1656       return FALSE;
1657   }
1658
1659   while (g_ascii_isspace (*s))
1660     s++;
1661   if (*s == '[') {
1662     ret = gst_structure_parse_range (s, &s, value, type);
1663   } else if (*s == '{') {
1664     ret = gst_structure_parse_list (s, &s, value, type);
1665   } else if (*s == '<') {
1666     ret = gst_structure_parse_array (s, &s, value, type);
1667   } else {
1668     value_s = s;
1669     if (!gst_structure_parse_string (s, &value_end, &s))
1670       return FALSE;
1671
1672     c = *value_end;
1673     *value_end = 0;
1674     if (type == G_TYPE_INVALID) {
1675       GType try_types[] =
1676           { G_TYPE_INT, G_TYPE_DOUBLE, GST_TYPE_FRACTION, G_TYPE_STRING };
1677       int i;
1678
1679       for (i = 0; i < 4; i++) {
1680         g_value_init (value, try_types[i]);
1681         ret = gst_value_deserialize (value, value_s);
1682         if (ret)
1683           break;
1684         g_value_unset (value);
1685       }
1686     } else {
1687       g_value_init (value, type);
1688
1689       ret = gst_value_deserialize (value, value_s);
1690     }
1691     *value_end = c;
1692   }
1693
1694   *after = s;
1695
1696   return ret;
1697 }
1698
1699 /**
1700  * gst_structure_from_string:
1701  * @string: a string representation of a #GstStructure.
1702  * @end: pointer to store the end of the string in.
1703  *
1704  * Creates a #GstStructure from a string representation.
1705  * If end is not NULL, a pointer to the place inside the given string
1706  * where parsing ended will be returned.
1707  *
1708  * Returns: a new #GstStructure or NULL when the string could not
1709  * be parsed. Free after usage.
1710  */
1711 GstStructure *
1712 gst_structure_from_string (const gchar * string, gchar ** end)
1713 {
1714   char *name;
1715   char *copy;
1716   char *w;
1717   char *r;
1718   char save;
1719   GstStructure *structure = NULL;
1720   GstStructureField field = { 0 };
1721
1722   g_return_val_if_fail (string != NULL, NULL);
1723
1724   copy = g_strdup (string);
1725   r = copy;
1726
1727   name = r;
1728   if (!gst_structure_parse_string (r, &w, &r))
1729     goto error;
1730
1731   while (g_ascii_isspace (*r) || (r[0] == '\\' && g_ascii_isspace (r[1])))
1732     r++;
1733   if (*r != 0 && *r != ';' && *r != ',')
1734     goto error;
1735
1736   save = *w;
1737   *w = 0;
1738   structure = gst_structure_empty_new (name);
1739   *w = save;
1740
1741   while (*r && (*r != ';')) {
1742     if (*r != ',')
1743       goto error;
1744     r++;
1745     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
1746                 && g_ascii_isspace (r[1]))))
1747       r++;
1748
1749     memset (&field, 0, sizeof (field));
1750     if (!gst_structure_parse_field (r, &r, &field))
1751       goto error;
1752     gst_structure_set_field (structure, &field);
1753     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
1754                 && g_ascii_isspace (r[1]))))
1755       r++;
1756   }
1757
1758   if (end)
1759     *end = (char *) string + (r - copy);
1760
1761   g_free (copy);
1762   return structure;
1763
1764 error:
1765   if (structure)
1766     gst_structure_free (structure);
1767   g_free (copy);
1768   return NULL;
1769 }
1770
1771 static void
1772 gst_structure_transform_to_string (const GValue * src_value,
1773     GValue * dest_value)
1774 {
1775   g_return_if_fail (src_value != NULL);
1776   g_return_if_fail (dest_value != NULL);
1777
1778   dest_value->data[0].v_pointer =
1779       gst_structure_to_string (src_value->data[0].v_pointer);
1780 }
1781
1782 static GstStructure *
1783 gst_structure_copy_conditional (const GstStructure * structure)
1784 {
1785   if (structure)
1786     return gst_structure_copy (structure);
1787   return NULL;
1788 }
1789
1790 /* fixate utility functions */
1791
1792 /**
1793  * gst_structure_fixate_field_nearest_int:
1794  * @structure: a #GstStructure
1795  * @field_name: a field in @structure
1796  * @target: the target value of the fixation
1797  *
1798  * Fixates a #GstStructure by changing the given field to the nearest
1799  * integer to @target that is a subset of the existing field.
1800  *
1801  * Returns: TRUE if the structure could be fixated
1802  */
1803 gboolean
1804 gst_structure_fixate_field_nearest_int (GstStructure * structure,
1805     const char *field_name, int target)
1806 {
1807   const GValue *value;
1808
1809   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
1810   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1811
1812   value = gst_structure_get_value (structure, field_name);
1813
1814   if (G_VALUE_TYPE (value) == G_TYPE_INT) {
1815     /* already fixed */
1816     return FALSE;
1817   } else if (G_VALUE_TYPE (value) == GST_TYPE_INT_RANGE) {
1818     int x;
1819
1820     x = gst_value_get_int_range_min (value);
1821     if (target < x)
1822       target = x;
1823     x = gst_value_get_int_range_max (value);
1824     if (target > x)
1825       target = x;
1826     gst_structure_set (structure, field_name, G_TYPE_INT, target, NULL);
1827     return TRUE;
1828   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1829     const GValue *list_value;
1830     int i, n;
1831     int best = 0;
1832     int best_index = -1;
1833
1834     n = gst_value_list_get_size (value);
1835     for (i = 0; i < n; i++) {
1836       list_value = gst_value_list_get_value (value, i);
1837       if (G_VALUE_TYPE (list_value) == G_TYPE_INT) {
1838         int x = g_value_get_int (list_value);
1839
1840         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
1841           best_index = i;
1842           best = x;
1843         }
1844       }
1845     }
1846     if (best_index != -1) {
1847       gst_structure_set (structure, field_name, G_TYPE_INT, best, NULL);
1848       return TRUE;
1849     }
1850     return FALSE;
1851   }
1852
1853   return FALSE;
1854 }
1855
1856 /**
1857  * gst_structure_fixate_field_nearest_double:
1858  * @structure: a #GstStructure
1859  * @field_name: a field in @structure
1860  * @target: the target value of the fixation
1861  *
1862  * Fixates a #GstStructure by changing the given field to the nearest
1863  * double to @target that is a subset of the existing field.
1864  *
1865  * Returns: TRUE if the structure could be fixated
1866  */
1867 gboolean
1868 gst_structure_fixate_field_nearest_double (GstStructure * structure,
1869     const char *field_name, double target)
1870 {
1871   const GValue *value;
1872
1873   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
1874   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1875
1876   value = gst_structure_get_value (structure, field_name);
1877
1878   if (G_VALUE_TYPE (value) == G_TYPE_DOUBLE) {
1879     /* already fixed */
1880     return FALSE;
1881   } else if (G_VALUE_TYPE (value) == GST_TYPE_DOUBLE_RANGE) {
1882     double x;
1883
1884     x = gst_value_get_double_range_min (value);
1885     if (target < x)
1886       target = x;
1887     x = gst_value_get_double_range_max (value);
1888     if (target > x)
1889       target = x;
1890     gst_structure_set (structure, field_name, G_TYPE_DOUBLE, target, NULL);
1891     return TRUE;
1892   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1893     const GValue *list_value;
1894     int i, n;
1895     double best = 0;
1896     int best_index = -1;
1897
1898     n = gst_value_list_get_size (value);
1899     for (i = 0; i < n; i++) {
1900       list_value = gst_value_list_get_value (value, i);
1901       if (G_VALUE_TYPE (list_value) == G_TYPE_DOUBLE) {
1902         double x = g_value_get_double (list_value);
1903
1904         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
1905           best_index = i;
1906           best = x;
1907         }
1908       }
1909     }
1910     if (best_index != -1) {
1911       gst_structure_set (structure, field_name, G_TYPE_DOUBLE, best, NULL);
1912       return TRUE;
1913     }
1914     return FALSE;
1915   }
1916
1917   return FALSE;
1918
1919 }
1920
1921 /**
1922  * gst_structure_fixate_field_boolean:
1923  * @structure: a #GstStructure
1924  * @field_name: a field in @structure
1925  * @target: the target value of the fixation
1926  *
1927  * Fixates a #GstStructure by changing the given @field_name field to the given
1928  * @target boolean if that field is not fixed yet.
1929  *
1930  * Returns: TRUE if the structure could be fixated
1931  */
1932 gboolean
1933 gst_structure_fixate_field_boolean (GstStructure * structure,
1934     const char *field_name, gboolean target)
1935 {
1936   const GValue *value;
1937
1938   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
1939   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1940
1941   value = gst_structure_get_value (structure, field_name);
1942
1943   if (G_VALUE_TYPE (value) == G_TYPE_BOOLEAN) {
1944     /* already fixed */
1945     return FALSE;
1946   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1947     const GValue *list_value;
1948     int i, n;
1949     int best = 0;
1950     int best_index = -1;
1951
1952     n = gst_value_list_get_size (value);
1953     for (i = 0; i < n; i++) {
1954       list_value = gst_value_list_get_value (value, i);
1955       if (G_VALUE_TYPE (list_value) == G_TYPE_BOOLEAN) {
1956         gboolean x = g_value_get_boolean (list_value);
1957
1958         if (best_index == -1 || x == target) {
1959           best_index = i;
1960           best = x;
1961         }
1962       }
1963     }
1964     if (best_index != -1) {
1965       gst_structure_set (structure, field_name, G_TYPE_BOOLEAN, best, NULL);
1966       return TRUE;
1967     }
1968     return FALSE;
1969   }
1970
1971   return FALSE;
1972 }
1973
1974 /**
1975  * gst_structure_fixate_field_nearest_fraction:
1976  * @structure: a #GstStructure
1977  * @field_name: a field in @structure
1978  * @target_numerator: The numerator of the target value of the fixation
1979  * @target_denominator: The denominator of the target value of the fixation
1980  *
1981  * Fixates a #GstStructure by changing the given field to the nearest
1982  * fraction to @target_numerator/@target_denominator that is a subset
1983  * of the existing field.
1984  *
1985  * Returns: TRUE if the structure could be fixated
1986  */
1987 gboolean
1988 gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
1989     const char *field_name, const gint target_numerator,
1990     const gint target_denominator)
1991 {
1992   const GValue *value;
1993
1994   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
1995   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1996
1997   value = gst_structure_get_value (structure, field_name);
1998
1999   if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION) {
2000     /* already fixed */
2001     return FALSE;
2002   } else if (G_VALUE_TYPE (value) == GST_TYPE_FRACTION_RANGE) {
2003     const GValue *x, *new_value;
2004     GValue target = { 0 };
2005     g_value_init (&target, GST_TYPE_FRACTION);
2006     gst_value_set_fraction (&target, target_numerator, target_denominator);
2007
2008     new_value = &target;
2009     x = gst_value_get_fraction_range_min (value);
2010     if (gst_value_compare (&target, x) == GST_VALUE_LESS_THAN)
2011       new_value = x;
2012     x = gst_value_get_fraction_range_max (value);
2013     if (gst_value_compare (&target, x) == GST_VALUE_GREATER_THAN)
2014       new_value = x;
2015
2016     gst_structure_set_value (structure, field_name, new_value);
2017     g_value_unset (&target);
2018     return TRUE;
2019   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
2020     const GValue *list_value;
2021     int i, n;
2022     const GValue *best = NULL;
2023     GValue best_diff = { 0 };
2024     GValue cur_diff = { 0 };
2025     GValue target = { 0 };
2026     gboolean res = FALSE;
2027
2028     g_value_init (&best_diff, GST_TYPE_FRACTION);
2029     g_value_init (&cur_diff, GST_TYPE_FRACTION);
2030     g_value_init (&target, GST_TYPE_FRACTION);
2031
2032     gst_value_set_fraction (&target, target_numerator, target_denominator);
2033
2034     n = gst_value_list_get_size (value);
2035     for (i = 0; i < n; i++) {
2036       list_value = gst_value_list_get_value (value, i);
2037       if (G_VALUE_TYPE (list_value) == GST_TYPE_FRACTION) {
2038         if (best == NULL) {
2039           best = list_value;
2040           gst_value_set_fraction (&best_diff, 0, 1);
2041         } else {
2042           if (gst_value_compare (list_value, &target) == GST_VALUE_LESS_THAN)
2043             gst_value_fraction_subtract (&cur_diff, &target, list_value);
2044           else
2045             gst_value_fraction_subtract (&cur_diff, list_value, &target);
2046
2047           if (gst_value_compare (&cur_diff, &best_diff) == GST_VALUE_LESS_THAN) {
2048             best = list_value;
2049             g_value_copy (&cur_diff, &best_diff);
2050           }
2051         }
2052       }
2053     }
2054     if (best != NULL) {
2055       gst_structure_set_value (structure, field_name, best);
2056       res = TRUE;
2057     }
2058     g_value_unset (&best_diff);
2059     g_value_unset (&cur_diff);
2060     g_value_unset (&target);
2061     return res;
2062   }
2063
2064   return FALSE;
2065 }