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