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 (!gst_structure_type) {
  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 typedef struct _GstStructureAbbreviation
1173 {
1174   char *type_name;
1175   GType type;
1176 }
1177 GstStructureAbbreviation;
1178
1179 static GstStructureAbbreviation *
1180 gst_structure_get_abbrs (gint * n_abbrs)
1181 {
1182   static GstStructureAbbreviation *abbrs = NULL;
1183   static gint num = 0;
1184
1185   if (abbrs == NULL) {
1186     /* dynamically generate the array */
1187     GstStructureAbbreviation dyn_abbrs[] = {
1188       {"int", G_TYPE_INT}
1189       ,
1190       {"i", G_TYPE_INT}
1191       ,
1192       {"float", G_TYPE_FLOAT}
1193       ,
1194       {"f", G_TYPE_FLOAT}
1195       ,
1196       {"double", G_TYPE_DOUBLE}
1197       ,
1198       {"d", G_TYPE_DOUBLE}
1199       ,
1200       {"buffer", GST_TYPE_BUFFER}
1201       ,
1202       {"fourcc", GST_TYPE_FOURCC}
1203       ,
1204       {"4", GST_TYPE_FOURCC}
1205       ,
1206       {"fraction", GST_TYPE_FRACTION}
1207       ,
1208       {"boolean", G_TYPE_BOOLEAN}
1209       ,
1210       {"bool", G_TYPE_BOOLEAN}
1211       ,
1212       {"b", G_TYPE_BOOLEAN}
1213       ,
1214       {"string", G_TYPE_STRING}
1215       ,
1216       {"str", G_TYPE_STRING}
1217       ,
1218       {"s", G_TYPE_STRING}
1219     };
1220     num = G_N_ELEMENTS (dyn_abbrs);
1221     /* permanently allocate and copy the array now */
1222     abbrs = g_new0 (GstStructureAbbreviation, num);
1223     memcpy (abbrs, dyn_abbrs, sizeof (GstStructureAbbreviation) * num);
1224   }
1225   *n_abbrs = num;
1226
1227   return abbrs;
1228 }
1229
1230 static GType
1231 gst_structure_from_abbr (const char *type_name)
1232 {
1233   int i;
1234   GstStructureAbbreviation *abbrs;
1235   gint n_abbrs;
1236
1237   g_return_val_if_fail (type_name != NULL, G_TYPE_INVALID);
1238
1239   abbrs = gst_structure_get_abbrs (&n_abbrs);
1240
1241   for (i = 0; i < n_abbrs; i++) {
1242     if (strcmp (type_name, abbrs[i].type_name) == 0) {
1243       return abbrs[i].type;
1244     }
1245   }
1246
1247   /* this is the fallback */
1248   return g_type_from_name (type_name);
1249 }
1250
1251 static const char *
1252 gst_structure_to_abbr (GType type)
1253 {
1254   int i;
1255   GstStructureAbbreviation *abbrs;
1256   gint n_abbrs;
1257
1258   g_return_val_if_fail (type != G_TYPE_INVALID, NULL);
1259
1260   abbrs = gst_structure_get_abbrs (&n_abbrs);
1261
1262   for (i = 0; i < n_abbrs; i++) {
1263     if (type == abbrs[i].type) {
1264       return abbrs[i].type_name;
1265     }
1266   }
1267
1268   return g_type_name (type);
1269 }
1270
1271 static GType
1272 gst_structure_value_get_generic_type (GValue * val)
1273 {
1274   if (G_VALUE_TYPE (val) == GST_TYPE_LIST
1275       || G_VALUE_TYPE (val) == GST_TYPE_ARRAY) {
1276     GArray *array = g_value_peek_pointer (val);
1277
1278     if (array->len > 0) {
1279       GValue *value = &g_array_index (array, GValue, 0);
1280
1281       return gst_structure_value_get_generic_type (value);
1282     } else {
1283       return G_TYPE_INT;
1284     }
1285   } else if (G_VALUE_TYPE (val) == GST_TYPE_INT_RANGE) {
1286     return G_TYPE_INT;
1287   } else if (G_VALUE_TYPE (val) == GST_TYPE_DOUBLE_RANGE) {
1288     return G_TYPE_DOUBLE;
1289   }
1290   return G_VALUE_TYPE (val);
1291 }
1292
1293 #define GST_ASCII_IS_STRING(c) (g_ascii_isalnum((c)) || ((c) == '_') || \
1294       ((c) == '-') || ((c) == '+') || ((c) == '/') || ((c) == ':') || \
1295       ((c) == '.'))
1296
1297 /**
1298  * gst_structure_to_string:
1299  * @structure: a #GstStructure
1300  *
1301  * Converts @structure to a human-readable string representation.
1302  *
1303  * Returns: a pointer to string allocated by g_malloc(). g_free after
1304  * usage.
1305  */
1306 gchar *
1307 gst_structure_to_string (const GstStructure * structure)
1308 {
1309   GstStructureField *field;
1310   GString *s;
1311   guint i;
1312
1313   /* NOTE:  This function is potentially called by the debug system,
1314    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1315    * should be careful to avoid recursion.  This includes any functions
1316    * called by gst_structure_to_string.  In particular, calls should
1317    * not use the GST_PTR_FORMAT extension.  */
1318
1319   g_return_val_if_fail (structure != NULL, NULL);
1320
1321   s = g_string_new ("");
1322   /* FIXME this string may need to be escaped */
1323   g_string_append_printf (s, "%s", g_quark_to_string (structure->name));
1324   for (i = 0; i < structure->fields->len; i++) {
1325     char *t;
1326     GType type;
1327
1328     field = GST_STRUCTURE_FIELD (structure, i);
1329
1330     t = gst_value_serialize (&field->value);
1331     type = gst_structure_value_get_generic_type (&field->value);
1332
1333     g_string_append_printf (s, ", %s=(%s)%s", g_quark_to_string (field->name),
1334         gst_structure_to_abbr (type), GST_STR_NULL (t));
1335     g_free (t);
1336   }
1337   return g_string_free (s, FALSE);
1338 }
1339
1340 /*
1341  * r will still point to the string. if end == next, the string will not be
1342  * null-terminated. In all other cases it will be.
1343  * end = pointer to char behind end of string, next = pointer to start of
1344  * unread data.
1345  * THIS FUNCTION MODIFIES THE STRING AND DETECTS INSIDE A NONTERMINATED STRING
1346  */
1347 static gboolean
1348 gst_structure_parse_string (gchar * s, gchar ** end, gchar ** next)
1349 {
1350   gchar *w;
1351
1352   if (*s == 0)
1353     return FALSE;
1354
1355   if (*s != '"') {
1356     int ret;
1357
1358     ret = gst_structure_parse_simple_string (s, end);
1359     *next = *end;
1360
1361     return ret;
1362   }
1363
1364   w = s;
1365   s++;
1366   while (*s != '"') {
1367     if (*s == 0)
1368       return FALSE;
1369
1370     if (*s == '\\') {
1371       s++;
1372     }
1373
1374     *w = *s;
1375     w++;
1376     s++;
1377   }
1378   s++;
1379
1380   *end = w;
1381   *next = s;
1382
1383   return TRUE;
1384 }
1385
1386 static gboolean
1387 gst_structure_parse_range (gchar * s, gchar ** after, GValue * value,
1388     GType type)
1389 {
1390   GValue value1 = { 0 };
1391   GValue value2 = { 0 };
1392   GType range_type;
1393   gboolean ret;
1394
1395
1396   if (*s != '[')
1397     return FALSE;
1398   s++;
1399
1400   ret = gst_structure_parse_value (s, &s, &value1, type);
1401   if (ret == FALSE)
1402     return FALSE;
1403
1404   while (g_ascii_isspace (*s))
1405     s++;
1406
1407   if (*s != ',')
1408     return FALSE;
1409   s++;
1410
1411   while (g_ascii_isspace (*s))
1412     s++;
1413
1414   ret = gst_structure_parse_value (s, &s, &value2, type);
1415   if (ret == FALSE)
1416     return FALSE;
1417
1418   while (g_ascii_isspace (*s))
1419     s++;
1420
1421   if (*s != ']')
1422     return FALSE;
1423   s++;
1424
1425   if (G_VALUE_TYPE (&value1) != G_VALUE_TYPE (&value2))
1426     return FALSE;
1427
1428   if (G_VALUE_TYPE (&value1) == G_TYPE_DOUBLE) {
1429     range_type = GST_TYPE_DOUBLE_RANGE;
1430   } else if (G_VALUE_TYPE (&value1) == G_TYPE_INT) {
1431     range_type = GST_TYPE_INT_RANGE;
1432   } else {
1433     return FALSE;
1434   }
1435
1436   g_value_init (value, range_type);
1437   if (range_type == GST_TYPE_DOUBLE_RANGE) {
1438     gst_value_set_double_range (value, g_value_get_double (&value1),
1439         g_value_get_double (&value2));
1440   } else {
1441     gst_value_set_int_range (value, g_value_get_int (&value1),
1442         g_value_get_int (&value2));
1443   }
1444
1445   *after = s;
1446   return TRUE;
1447 }
1448
1449 static gboolean
1450 gst_structure_parse_any_list (gchar * s, gchar ** after, GValue * value,
1451     GType type, GType list_type, char begin, char end)
1452 {
1453   GValue list_value = { 0 };
1454   gboolean ret;
1455   GArray *array;
1456
1457   g_value_init (value, list_type);
1458   array = g_value_peek_pointer (value);
1459
1460   if (*s != begin)
1461     return FALSE;
1462   s++;
1463
1464   while (g_ascii_isspace (*s))
1465     s++;
1466   if (*s == end) {
1467     s++;
1468     *after = s;
1469     return TRUE;
1470   }
1471
1472   ret = gst_structure_parse_value (s, &s, &list_value, type);
1473   if (ret == FALSE)
1474     return FALSE;
1475
1476   g_array_append_val (array, list_value);
1477
1478   while (g_ascii_isspace (*s))
1479     s++;
1480
1481   while (*s != end) {
1482     if (*s != ',')
1483       return FALSE;
1484     s++;
1485
1486     while (g_ascii_isspace (*s))
1487       s++;
1488
1489     memset (&list_value, 0, sizeof (list_value));
1490     ret = gst_structure_parse_value (s, &s, &list_value, type);
1491     if (ret == FALSE)
1492       return FALSE;
1493
1494     g_array_append_val (array, list_value);
1495     while (g_ascii_isspace (*s))
1496       s++;
1497   }
1498
1499   s++;
1500
1501   *after = s;
1502   return TRUE;
1503 }
1504
1505 static gboolean
1506 gst_structure_parse_list (gchar * s, gchar ** after, GValue * value, GType type)
1507 {
1508   return gst_structure_parse_any_list (s, after, value, type, GST_TYPE_LIST,
1509       '{', '}');
1510 }
1511
1512 static gboolean
1513 gst_structure_parse_array (gchar * s, gchar ** after, GValue * value,
1514     GType type)
1515 {
1516   return gst_structure_parse_any_list (s, after, value, type,
1517       GST_TYPE_ARRAY, '<', '>');
1518 }
1519
1520 static gboolean
1521 gst_structure_parse_simple_string (gchar * str, gchar ** end)
1522 {
1523   char *s = str;
1524
1525   while (GST_ASCII_IS_STRING (*s)) {
1526     s++;
1527   }
1528
1529   *end = s;
1530
1531   return (s != str);
1532 }
1533
1534 static gboolean
1535 gst_structure_parse_field (gchar * str,
1536     gchar ** after, GstStructureField * field)
1537 {
1538   gchar *name;
1539   gchar *name_end;
1540   gchar *s;
1541   gchar c;
1542
1543   s = str;
1544
1545   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
1546     s++;
1547   name = s;
1548   if (!gst_structure_parse_simple_string (s, &name_end))
1549     return FALSE;
1550
1551   s = name_end;
1552   while (g_ascii_isspace (*s) || (s[0] == '\\' && g_ascii_isspace (s[1])))
1553     s++;
1554
1555   if (*s != '=')
1556     return FALSE;
1557   s++;
1558
1559   c = *name_end;
1560   *name_end = 0;
1561   field->name = g_quark_from_string (name);
1562   *name_end = c;
1563
1564   if (!gst_structure_parse_value (s, &s, &field->value, G_TYPE_INVALID))
1565     return FALSE;
1566
1567   *after = s;
1568   return TRUE;
1569 }
1570
1571 static gboolean
1572 gst_structure_parse_value (gchar * str,
1573     gchar ** after, GValue * value, GType default_type)
1574 {
1575   gchar *type_name;
1576   gchar *type_end;
1577   gchar *value_s;
1578   gchar *value_end;
1579   gchar *s;
1580   gchar c;
1581   int ret = 0;
1582   GType type = default_type;
1583
1584
1585   s = str;
1586   while (g_ascii_isspace (*s))
1587     s++;
1588
1589   type_name = NULL;
1590   if (*s == '(') {
1591     type = G_TYPE_INVALID;
1592
1593     s++;
1594     while (g_ascii_isspace (*s))
1595       s++;
1596     type_name = s;
1597     if (!gst_structure_parse_simple_string (s, &type_end))
1598       return FALSE;
1599     s = type_end;
1600     while (g_ascii_isspace (*s))
1601       s++;
1602     if (*s != ')')
1603       return FALSE;
1604     s++;
1605     while (g_ascii_isspace (*s))
1606       s++;
1607
1608     c = *type_end;
1609     *type_end = 0;
1610     type = gst_structure_from_abbr (type_name);
1611     *type_end = c;
1612
1613     if (type == G_TYPE_INVALID)
1614       return FALSE;
1615   }
1616
1617   while (g_ascii_isspace (*s))
1618     s++;
1619   if (*s == '[') {
1620     ret = gst_structure_parse_range (s, &s, value, type);
1621   } else if (*s == '{') {
1622     ret = gst_structure_parse_list (s, &s, value, type);
1623   } else if (*s == '<') {
1624     ret = gst_structure_parse_array (s, &s, value, type);
1625   } else {
1626     value_s = s;
1627     if (!gst_structure_parse_string (s, &value_end, &s))
1628       return FALSE;
1629
1630     c = *value_end;
1631     *value_end = 0;
1632     if (type == G_TYPE_INVALID) {
1633       GType try_types[] = { G_TYPE_INT, G_TYPE_DOUBLE, G_TYPE_STRING };
1634       int i;
1635
1636       for (i = 0; i < 3; i++) {
1637         g_value_init (value, try_types[i]);
1638         ret = gst_value_deserialize (value, value_s);
1639         if (ret)
1640           break;
1641         g_value_unset (value);
1642       }
1643     } else {
1644       g_value_init (value, type);
1645
1646       ret = gst_value_deserialize (value, value_s);
1647     }
1648     *value_end = c;
1649   }
1650
1651   *after = s;
1652
1653   return ret;
1654 }
1655
1656 /**
1657  * gst_structure_from_string:
1658  * @string: a string representation of a #GstStructure.
1659  * @end: pointer to store the end of the string in.
1660  *
1661  * Creates a #GstStructure from a string representation.
1662  * If end is not NULL, a pointer to the place inside the given string
1663  * where parsing ended will be returned.
1664  *
1665  * Returns: a new #GstStructure or NULL when the string could not
1666  * be parsed. Free after usage.
1667  */
1668 GstStructure *
1669 gst_structure_from_string (const gchar * string, gchar ** end)
1670 {
1671   char *name;
1672   char *copy;
1673   char *w;
1674   char *r;
1675   char save;
1676   GstStructure *structure = NULL;
1677   GstStructureField field = { 0 };
1678
1679   g_return_val_if_fail (string != NULL, NULL);
1680
1681   copy = g_strdup (string);
1682   r = copy;
1683
1684   name = r;
1685   if (!gst_structure_parse_string (r, &w, &r))
1686     goto error;
1687
1688   while (g_ascii_isspace (*r) || (r[0] == '\\' && g_ascii_isspace (r[1])))
1689     r++;
1690   if (*r != 0 && *r != ';' && *r != ',')
1691     goto error;
1692
1693   save = *w;
1694   *w = 0;
1695   structure = gst_structure_empty_new (name);
1696   *w = save;
1697
1698   while (*r && (*r != ';')) {
1699     if (*r != ',')
1700       goto error;
1701     r++;
1702     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
1703                 && g_ascii_isspace (r[1]))))
1704       r++;
1705
1706     memset (&field, 0, sizeof (field));
1707     if (!gst_structure_parse_field (r, &r, &field))
1708       goto error;
1709     gst_structure_set_field (structure, &field);
1710     while (*r && (g_ascii_isspace (*r) || (r[0] == '\\'
1711                 && g_ascii_isspace (r[1]))))
1712       r++;
1713   }
1714
1715   if (end)
1716     *end = (char *) string + (r - copy);
1717
1718   g_free (copy);
1719   return structure;
1720
1721 error:
1722   if (structure)
1723     gst_structure_free (structure);
1724   g_free (copy);
1725   return NULL;
1726 }
1727
1728 static void
1729 gst_structure_transform_to_string (const GValue * src_value,
1730     GValue * dest_value)
1731 {
1732   g_return_if_fail (src_value != NULL);
1733   g_return_if_fail (dest_value != NULL);
1734
1735   dest_value->data[0].v_pointer =
1736       gst_structure_to_string (src_value->data[0].v_pointer);
1737 }
1738
1739 static GstStructure *
1740 gst_structure_copy_conditional (const GstStructure * structure)
1741 {
1742   if (structure)
1743     return gst_structure_copy (structure);
1744   return NULL;
1745 }
1746
1747 /* fixate utility functions */
1748
1749 /**
1750  * gst_structure_fixate_field_nearest_int:
1751  * @structure: a #GstStructure
1752  * @field_name: a field in @structure
1753  * @target: the target value of the fixation
1754  *
1755  * Fixates a #GstStructure by changing the given field to the nearest
1756  * integer to @target that is a subset of the existing field.
1757  *
1758  * Returns: TRUE if the structure could be fixated
1759  */
1760 gboolean
1761 gst_structure_fixate_field_nearest_int (GstStructure * structure,
1762     const char *field_name, int target)
1763 {
1764   const GValue *value;
1765
1766   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
1767   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1768
1769   value = gst_structure_get_value (structure, field_name);
1770
1771   if (G_VALUE_TYPE (value) == G_TYPE_INT) {
1772     /* already fixed */
1773     return FALSE;
1774   } else if (G_VALUE_TYPE (value) == GST_TYPE_INT_RANGE) {
1775     int x;
1776
1777     x = gst_value_get_int_range_min (value);
1778     if (target < x)
1779       target = x;
1780     x = gst_value_get_int_range_max (value);
1781     if (target > x)
1782       target = x;
1783     gst_structure_set (structure, field_name, G_TYPE_INT, target, NULL);
1784     return TRUE;
1785   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1786     const GValue *list_value;
1787     int i, n;
1788     int best = 0;
1789     int best_index = -1;
1790
1791     n = gst_value_list_get_size (value);
1792     for (i = 0; i < n; i++) {
1793       list_value = gst_value_list_get_value (value, i);
1794       if (G_VALUE_TYPE (list_value) == G_TYPE_INT) {
1795         int x = g_value_get_int (list_value);
1796
1797         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
1798           best_index = i;
1799           best = x;
1800         }
1801       }
1802     }
1803     if (best_index != -1) {
1804       gst_structure_set (structure, field_name, G_TYPE_INT, best, NULL);
1805       return TRUE;
1806     }
1807     return FALSE;
1808   }
1809
1810   return FALSE;
1811 }
1812
1813 /**
1814  * gst_structure_fixate_field_nearest_double:
1815  * @structure: a #GstStructure
1816  * @field_name: a field in @structure
1817  * @target: the target value of the fixation
1818  *
1819  * Fixates a #GstStructure by changing the given field to the nearest
1820  * double to @target that is a subset of the existing field.
1821  *
1822  * Returns: TRUE if the structure could be fixated
1823  */
1824 gboolean
1825 gst_structure_fixate_field_nearest_double (GstStructure * structure,
1826     const char *field_name, double target)
1827 {
1828   const GValue *value;
1829
1830   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
1831   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1832
1833   value = gst_structure_get_value (structure, field_name);
1834
1835   if (G_VALUE_TYPE (value) == G_TYPE_DOUBLE) {
1836     /* already fixed */
1837     return FALSE;
1838   } else if (G_VALUE_TYPE (value) == GST_TYPE_DOUBLE_RANGE) {
1839     double x;
1840
1841     x = gst_value_get_double_range_min (value);
1842     if (target < x)
1843       target = x;
1844     x = gst_value_get_double_range_max (value);
1845     if (target > x)
1846       target = x;
1847     gst_structure_set (structure, field_name, G_TYPE_DOUBLE, target, NULL);
1848     return TRUE;
1849   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1850     const GValue *list_value;
1851     int i, n;
1852     double best = 0;
1853     int best_index = -1;
1854
1855     n = gst_value_list_get_size (value);
1856     for (i = 0; i < n; i++) {
1857       list_value = gst_value_list_get_value (value, i);
1858       if (G_VALUE_TYPE (list_value) == G_TYPE_DOUBLE) {
1859         double x = g_value_get_double (list_value);
1860
1861         if (best_index == -1 || (ABS (target - x) < ABS (target - best))) {
1862           best_index = i;
1863           best = x;
1864         }
1865       }
1866     }
1867     if (best_index != -1) {
1868       gst_structure_set (structure, field_name, G_TYPE_DOUBLE, best, NULL);
1869       return TRUE;
1870     }
1871     return FALSE;
1872   }
1873
1874   return FALSE;
1875
1876 }
1877
1878 /**
1879  * gst_structure_fixate_field_boolean:
1880  * @structure: a #GstStructure
1881  * @field_name: a field in @structure
1882  * @target: the target value of the fixation
1883  *
1884  * Fixates a #GstStructure by changing the given @field_name field to the given
1885  * @target boolean if that field is not fixed yet.
1886  *
1887  * Returns: TRUE if the structure could be fixated
1888  */
1889 gboolean
1890 gst_structure_fixate_field_boolean (GstStructure * structure,
1891     const char *field_name, gboolean target)
1892 {
1893   const GValue *value;
1894
1895   g_return_val_if_fail (gst_structure_has_field (structure, field_name), FALSE);
1896   g_return_val_if_fail (IS_MUTABLE (structure), FALSE);
1897
1898   value = gst_structure_get_value (structure, field_name);
1899
1900   if (G_VALUE_TYPE (value) == G_TYPE_BOOLEAN) {
1901     /* already fixed */
1902     return FALSE;
1903   } else if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1904     const GValue *list_value;
1905     int i, n;
1906     int best = 0;
1907     int best_index = -1;
1908
1909     n = gst_value_list_get_size (value);
1910     for (i = 0; i < n; i++) {
1911       list_value = gst_value_list_get_value (value, i);
1912       if (G_VALUE_TYPE (list_value) == G_TYPE_BOOLEAN) {
1913         gboolean x = g_value_get_boolean (list_value);
1914
1915         if (best_index == -1 || x == target) {
1916           best_index = i;
1917           best = x;
1918         }
1919       }
1920     }
1921     if (best_index != -1) {
1922       gst_structure_set (structure, field_name, G_TYPE_BOOLEAN, best, NULL);
1923       return TRUE;
1924     }
1925     return FALSE;
1926   }
1927
1928   return FALSE;
1929 }