gst/gststructure.c

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