gst/gstquery.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wim.taymans@chello.be>
   4  *                    2005 Wim Taymans <wim@fluendo.com>
   5  *
   6  * gstquery.c: GstQueryType registration and Query parsing/creation
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 /**
  25  * SECTION:gstquery
  26  * @short_description: Dynamically register new query types. Provide functions
  27  *                     to create queries, and to set and parse values in them.
  28  * @see_also: #GstPad, #GstElement
  29  *
  30  * GstQuery functions are used to register new query types to the gstreamer
  31  * core and use them.
  32  * Queries can be performed on pads (gst_pad_query()) and elements
  33  * (gst_element_query()). Please note that some queries might need a running
  34  * pipeline to work.
  35  *
  36  * Queries can be created using the gst_query_new_*() functions.
  37  * Query values can be set using gst_query_set_*(), and parsed using
  38  * gst_query_parse_*() helpers.
  39  *
  40  * The following example shows how to query the duration of a pipeline:
  41  *
  42  * <example>
  43  *  <title>Query duration on a pipeline</title>
  44  *  <programlisting>
  45  *  GstQuery *query;
  46  *  gboolean res;
  47  *  query = gst_query_new_duration (GST_FORMAT_TIME);
  48  *  res = gst_element_query (pipeline, query);
  49  *  if (res) {
  50  *    gint64 duration;
  51  *    gst_query_parse_duration (query, NULL, &amp;duration);
  52  *    g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
  53  *  }
  54  *  else {
  55  *    g_print ("duration query failed...");
  56  *  }
  57  *  gst_query_unref (query);
  58  *  </programlisting>
  59  * </example>
  60  *
  61  * Last reviewed on 2006-02-14 (0.10.4)
  62  */
  63
  64 #include "gst_private.h"
  65 #include "gstinfo.h"
  66 #include "gstquery.h"
  67 #include "gstvalue.h"
  68 #include "gstenumtypes.h"
  69 #include "gstquark.h"
  70 #include "gsturi.h"
  71
  72 GST_DEBUG_CATEGORY_STATIC (gst_query_debug);
  73 #define GST_CAT_DEFAULT gst_query_debug
  74
  75 static GType _gst_query_type = 0;
  76
  77 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
  78 static GList *_gst_queries = NULL;
  79 static GHashTable *_nick_to_query = NULL;
  80 static GHashTable *_query_type_to_nick = NULL;
  81 static guint32 _n_values = 1;   /* we start from 1 because 0 reserved for NONE */
  82
  83 static GstQueryTypeDefinition standard_definitions[] = {
  84   {GST_QUERY_POSITION, "position", "Current position", 0},
  85   {GST_QUERY_DURATION, "duration", "Total duration", 0},
  86   {GST_QUERY_LATENCY, "latency", "Latency", 0},
  87   {GST_QUERY_JITTER, "jitter", "Jitter", 0},
  88   {GST_QUERY_RATE, "rate", "Configured rate 1000000 = 1", 0},
  89   {GST_QUERY_SEEKING, "seeking", "Seeking capabilities and parameters", 0},
  90   {GST_QUERY_SEGMENT, "segment", "currently configured segment", 0},
  91   {GST_QUERY_CONVERT, "convert", "Converting between formats", 0},
  92   {GST_QUERY_FORMATS, "formats", "Supported formats for conversion", 0},
  93   {GST_QUERY_BUFFERING, "buffering", "Buffering status", 0},
  94   {GST_QUERY_CUSTOM, "custom", "Custom query", 0},
  95   {GST_QUERY_URI, "uri", "URI of the source or sink", 0},
  96   {0, NULL, NULL, 0}
  97 };
  98
  99 void
 100 _gst_query_initialize (void)
 101 {
 102   GstQueryTypeDefinition *standards = standard_definitions;
 103
 104   GST_CAT_INFO (GST_CAT_GST_INIT, "init queries");
 105
 106   GST_DEBUG_CATEGORY_INIT (gst_query_debug, "query", 0, "query system");
 107
 108   g_static_mutex_lock (&mutex);
 109   if (_nick_to_query == NULL) {
 110     _nick_to_query = g_hash_table_new (g_str_hash, g_str_equal);
 111     _query_type_to_nick = g_hash_table_new (NULL, NULL);
 112   }
 113
 114   while (standards->nick) {
 115     standards->quark = g_quark_from_static_string (standards->nick);
 116     g_hash_table_insert (_nick_to_query, (gpointer) standards->nick, standards);
 117     g_hash_table_insert (_query_type_to_nick,
 118         GINT_TO_POINTER (standards->value), standards);
 119
 120     _gst_queries = g_list_append (_gst_queries, standards);
 121     standards++;
 122     _n_values++;
 123   }
 124   g_static_mutex_unlock (&mutex);
 125
 126   gst_query_get_type ();
 127 }
 128
 129 /**
 130  * gst_query_type_get_name:
 131  * @query: the query type
 132  *
 133  * Get a printable name for the given query type. Do not modify or free.
 134  *
 135  * Returns: a reference to the static name of the query.
 136  */
 137 const gchar *
 138 gst_query_type_get_name (GstQueryType query)
 139 {
 140   const GstQueryTypeDefinition *def;
 141
 142   def = gst_query_type_get_details (query);
 143
 144   return def->nick;
 145 }
 146
 147 /**
 148  * gst_query_type_to_quark:
 149  * @query: the query type
 150  *
 151  * Get the unique quark for the given query type.
 152  *
 153  * Returns: the quark associated with the query type
 154  */
 155 GQuark
 156 gst_query_type_to_quark (GstQueryType query)
 157 {
 158   const GstQueryTypeDefinition *def;
 159
 160   def = gst_query_type_get_details (query);
 161
 162   return def->quark;
 163 }
 164
 165 GType
 166 gst_query_get_type (void)
 167 {
 168   if (G_UNLIKELY (_gst_query_type == 0)) {
 169     _gst_query_type = gst_mini_object_register ("GstQuery");
 170   }
 171   return _gst_query_type;
 172 }
 173
 174
 175 /**
 176  * gst_query_type_register:
 177  * @nick: The nick of the new query
 178  * @description: The description of the new query
 179  *
 180  * Create a new GstQueryType based on the nick or return an
 181  * already registered query with that nick
 182  *
 183  * Returns: A new GstQueryType or an already registered query
 184  * with the same nick.
 185  */
 186 GstQueryType
 187 gst_query_type_register (const gchar * nick, const gchar * description)
 188 {
 189   GstQueryTypeDefinition *query;
 190   GstQueryType lookup;
 191
 192   g_return_val_if_fail (nick != NULL, 0);
 193   g_return_val_if_fail (description != NULL, 0);
 194
 195   lookup = gst_query_type_get_by_nick (nick);
 196   if (lookup != GST_QUERY_NONE)
 197     return lookup;
 198
 199   query = g_slice_new (GstQueryTypeDefinition);
 200   query->value = _n_values;
 201   query->nick = g_strdup (nick);
 202   query->description = g_strdup (description);
 203   query->quark = g_quark_from_static_string (query->nick);
 204
 205   g_static_mutex_lock (&mutex);
 206   g_hash_table_insert (_nick_to_query, (gpointer) query->nick, query);
 207   g_hash_table_insert (_query_type_to_nick, GINT_TO_POINTER (query->value),
 208       query);
 209   _gst_queries = g_list_append (_gst_queries, query);
 210   _n_values++;
 211   g_static_mutex_unlock (&mutex);
 212
 213   return query->value;
 214 }
 215
 216 /**
 217  * gst_query_type_get_by_nick:
 218  * @nick: The nick of the query
 219  *
 220  * Get the query type registered with @nick.
 221  *
 222  * Returns: The query registered with @nick or #GST_QUERY_NONE
 223  * if the query was not registered.
 224  */
 225 GstQueryType
 226 gst_query_type_get_by_nick (const gchar * nick)
 227 {
 228   GstQueryTypeDefinition *query;
 229
 230   g_return_val_if_fail (nick != NULL, 0);
 231
 232   g_static_mutex_lock (&mutex);
 233   query = g_hash_table_lookup (_nick_to_query, nick);
 234   g_static_mutex_unlock (&mutex);
 235
 236   if (query != NULL)
 237     return query->value;
 238   else
 239     return GST_QUERY_NONE;
 240 }
 241
 242 /**
 243  * gst_query_types_contains:
 244  * @types: The query array to search
 245  * @type: the #GstQueryType to find
 246  *
 247  * See if the given #GstQueryType is inside the @types query types array.
 248  *
 249  * Returns: TRUE if the type is found inside the array
 250  */
 251 gboolean
 252 gst_query_types_contains (const GstQueryType * types, GstQueryType type)
 253 {
 254   if (!types)
 255     return FALSE;
 256
 257   while (*types) {
 258     if (*types == type)
 259       return TRUE;
 260
 261     types++;
 262   }
 263   return FALSE;
 264 }
 265
 266
 267 /**
 268  * gst_query_type_get_details:
 269  * @type: a #GstQueryType
 270  *
 271  * Get details about the given #GstQueryType.
 272  *
 273  * Returns: The #GstQueryTypeDefinition for @type or NULL on failure.
 274  */
 275 const GstQueryTypeDefinition *
 276 gst_query_type_get_details (GstQueryType type)
 277 {
 278   const GstQueryTypeDefinition *result;
 279
 280   g_static_mutex_lock (&mutex);
 281   result = g_hash_table_lookup (_query_type_to_nick, GINT_TO_POINTER (type));
 282   g_static_mutex_unlock (&mutex);
 283
 284   return result;
 285 }
 286
 287 /**
 288  * gst_query_type_iterate_definitions:
 289  *
 290  * Get a #GstIterator of all the registered query types. The definitions
 291  * iterated over are read only.
 292  *
 293  * Free-function: gst_iterator_free
 294  *
 295  * Returns: (transfer full): a #GstIterator of #GstQueryTypeDefinition.
 296  */
 297 GstIterator *
 298 gst_query_type_iterate_definitions (void)
 299 {
 300   GstIterator *result;
 301
 302   g_static_mutex_lock (&mutex);
 303   /* FIXME: register a boxed type for GstQueryTypeDefinition */
 304   result = gst_iterator_new_list (G_TYPE_POINTER,
 305       g_static_mutex_get_mutex (&mutex), &_n_values, &_gst_queries,
 306       NULL, NULL, NULL);
 307   g_static_mutex_unlock (&mutex);
 308
 309   return result;
 310 }
 311
 312 static void
 313 _gst_query_free (GstQuery * query)
 314 {
 315   g_return_if_fail (query != NULL);
 316
 317   if (query->structure) {
 318     gst_structure_set_parent_refcount (query->structure, NULL);
 319     gst_structure_free (query->structure);
 320   }
 321
 322   g_slice_free1 (GST_MINI_OBJECT_SIZE (query), query);
 323 }
 324
 325 static GstQuery *gst_query_new (GstQueryType type, GstStructure * structure);
 326
 327 static GstQuery *
 328 _gst_query_copy (GstQuery * query)
 329 {
 330   GstQuery *copy;
 331
 332   copy = gst_query_new (query->type, query->structure);
 333
 334   return copy;
 335 }
 336
 337 static GstQuery *
 338 gst_query_new (GstQueryType type, GstStructure * structure)
 339 {
 340   GstQuery *query;
 341
 342   query = g_slice_new0 (GstQuery);
 343
 344   gst_mini_object_init (GST_MINI_OBJECT_CAST (query),
 345       _gst_query_type, sizeof (GstQuery));
 346
 347   query->mini_object.copy = (GstMiniObjectCopyFunction) _gst_query_copy;
 348   query->mini_object.free = (GstMiniObjectFreeFunction) _gst_query_free;
 349
 350   GST_DEBUG ("creating new query %p %d", query, type);
 351
 352   query->type = type;
 353   query->structure = structure;
 354
 355   if (structure)
 356     gst_structure_set_parent_refcount (query->structure,
 357         &query->mini_object.refcount);
 358
 359   return query;
 360 }
 361
 362 /**
 363  * gst_query_new_position:
 364  * @format: the default #GstFormat for the new query
 365  *
 366  * Constructs a new query stream position query object. Use gst_query_unref()
 367  * when done with it. A position query is used to query the current position
 368  * of playback in the streams, in some format.
 369  *
 370  * Free-function: gst_query_unref
 371  *
 372  * Returns: (transfer full): a new #GstQuery
 373  */
 374 GstQuery *
 375 gst_query_new_position (GstFormat format)
 376 {
 377   GstQuery *query;
 378   GstStructure *structure;
 379
 380   structure = gst_structure_id_new (GST_QUARK (QUERY_POSITION),
 381       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 382       GST_QUARK (CURRENT), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
 383
 384   query = gst_query_new (GST_QUERY_POSITION, structure);
 385
 386   return query;
 387 }
 388
 389 /**
 390  * gst_query_set_position:
 391  * @query: a #GstQuery with query type GST_QUERY_POSITION
 392  * @format: the requested #GstFormat
 393  * @cur: the position to set
 394  *
 395  * Answer a position query by setting the requested value in the given format.
 396  */
 397 void
 398 gst_query_set_position (GstQuery * query, GstFormat format, gint64 cur)
 399 {
 400   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_POSITION);
 401
 402   gst_structure_id_set (query->structure,
 403       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 404       GST_QUARK (CURRENT), G_TYPE_INT64, cur, NULL);
 405 }
 406
 407 /**
 408  * gst_query_parse_position:
 409  * @query: a #GstQuery
 410  * @format: (out) (allow-none): the storage for the #GstFormat of the
 411  *     position values (may be NULL)
 412  * @cur: (out) (allow-none): the storage for the current position (may be NULL)
 413  *
 414  * Parse a position query, writing the format into @format, and the position
 415  * into @cur, if the respective parameters are non-NULL.
 416  */
 417 void
 418 gst_query_parse_position (GstQuery * query, GstFormat * format, gint64 * cur)
 419 {
 420   GstStructure *structure;
 421
 422   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_POSITION);
 423
 424   structure = query->structure;
 425   if (format)
 426     *format = g_value_get_enum (gst_structure_id_get_value (structure,
 427             GST_QUARK (FORMAT)));
 428   if (cur)
 429     *cur = g_value_get_int64 (gst_structure_id_get_value (structure,
 430             GST_QUARK (CURRENT)));
 431 }
 432
 433
 434 /**
 435  * gst_query_new_duration:
 436  * @format: the #GstFormat for this duration query
 437  *
 438  * Constructs a new stream duration query object to query in the given format.
 439  * Use gst_query_unref() when done with it. A duration query will give the
 440  * total length of the stream.
 441  *
 442  * Free-function: gst_query_unref
 443  *
 444  * Returns: (transfer full): a new #GstQuery
 445  */
 446 GstQuery *
 447 gst_query_new_duration (GstFormat format)
 448 {
 449   GstQuery *query;
 450   GstStructure *structure;
 451
 452   structure = gst_structure_id_new (GST_QUARK (QUERY_DURATION),
 453       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 454       GST_QUARK (DURATION), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
 455
 456   query = gst_query_new (GST_QUERY_DURATION, structure);
 457
 458   return query;
 459 }
 460
 461 /**
 462  * gst_query_set_duration:
 463  * @query: a #GstQuery
 464  * @format: the #GstFormat for the duration
 465  * @duration: the duration of the stream
 466  *
 467  * Answer a duration query by setting the requested value in the given format.
 468  */
 469 void
 470 gst_query_set_duration (GstQuery * query, GstFormat format, gint64 duration)
 471 {
 472   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_DURATION);
 473
 474   gst_structure_id_set (query->structure,
 475       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 476       GST_QUARK (DURATION), G_TYPE_INT64, duration, NULL);
 477 }
 478
 479 /**
 480  * gst_query_parse_duration:
 481  * @query: a #GstQuery
 482  * @format: (out) (allow-none): the storage for the #GstFormat of the duration
 483  *     value, or NULL.
 484  * @duration: (out) (allow-none): the storage for the total duration, or NULL.
 485  *
 486  * Parse a duration query answer. Write the format of the duration into @format,
 487  * and the value into @duration, if the respective variables are non-NULL.
 488  */
 489 void
 490 gst_query_parse_duration (GstQuery * query, GstFormat * format,
 491     gint64 * duration)
 492 {
 493   GstStructure *structure;
 494
 495   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_DURATION);
 496
 497   structure = query->structure;
 498   if (format)
 499     *format = g_value_get_enum (gst_structure_id_get_value (structure,
 500             GST_QUARK (FORMAT)));
 501   if (duration)
 502     *duration = g_value_get_int64 (gst_structure_id_get_value (structure,
 503             GST_QUARK (DURATION)));
 504 }
 505
 506 /**
 507  * gst_query_new_latency:
 508  *
 509  * Constructs a new latency query object.
 510  * Use gst_query_unref() when done with it. A latency query is usually performed
 511  * by sinks to compensate for additional latency introduced by elements in the
 512  * pipeline.
 513  *
 514  * Free-function: gst_query_unref
 515  *
 516  * Returns: (transfer full): a #GstQuery
 517  *
 518  * Since: 0.10.12
 519  */
 520 GstQuery *
 521 gst_query_new_latency (void)
 522 {
 523   GstQuery *query;
 524   GstStructure *structure;
 525
 526   structure = gst_structure_id_new (GST_QUARK (QUERY_LATENCY),
 527       GST_QUARK (LIVE), G_TYPE_BOOLEAN, FALSE,
 528       GST_QUARK (MIN_LATENCY), G_TYPE_UINT64, G_GUINT64_CONSTANT (0),
 529       GST_QUARK (MAX_LATENCY), G_TYPE_UINT64, G_GUINT64_CONSTANT (-1), NULL);
 530
 531   query = gst_query_new (GST_QUERY_LATENCY, structure);
 532
 533   return query;
 534 }
 535
 536 /**
 537  * gst_query_set_latency:
 538  * @query: a #GstQuery
 539  * @live: if there is a live element upstream
 540  * @min_latency: the minimal latency of the live element
 541  * @max_latency: the maximal latency of the live element
 542  *
 543  * Answer a latency query by setting the requested values in the given format.
 544  *
 545  * Since: 0.10.12
 546  */
 547 void
 548 gst_query_set_latency (GstQuery * query, gboolean live,
 549     GstClockTime min_latency, GstClockTime max_latency)
 550 {
 551   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_LATENCY);
 552
 553   gst_structure_id_set (query->structure,
 554       GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
 555       GST_QUARK (MIN_LATENCY), G_TYPE_UINT64, min_latency,
 556       GST_QUARK (MAX_LATENCY), G_TYPE_UINT64, max_latency, NULL);
 557 }
 558
 559 /**
 560  * gst_query_parse_latency:
 561  * @query: a #GstQuery
 562  * @live: (out) (allow-none): storage for live or NULL
 563  * @min_latency: (out) (allow-none): the storage for the min latency or NULL
 564  * @max_latency: (out) (allow-none): the storage for the max latency or NULL
 565  *
 566  * Parse a latency query answer.
 567  *
 568  * Since: 0.10.12
 569  */
 570 void
 571 gst_query_parse_latency (GstQuery * query, gboolean * live,
 572     GstClockTime * min_latency, GstClockTime * max_latency)
 573 {
 574   GstStructure *structure;
 575
 576   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_LATENCY);
 577
 578   structure = query->structure;
 579   if (live)
 580     *live =
 581         g_value_get_boolean (gst_structure_id_get_value (structure,
 582             GST_QUARK (LIVE)));
 583   if (min_latency)
 584     *min_latency = g_value_get_uint64 (gst_structure_id_get_value (structure,
 585             GST_QUARK (MIN_LATENCY)));
 586   if (max_latency)
 587     *max_latency = g_value_get_uint64 (gst_structure_id_get_value (structure,
 588             GST_QUARK (MAX_LATENCY)));
 589 }
 590
 591 /**
 592  * gst_query_new_convert:
 593  * @src_format: the source #GstFormat for the new query
 594  * @value: the value to convert
 595  * @dest_format: the target #GstFormat
 596  *
 597  * Constructs a new convert query object. Use gst_query_unref()
 598  * when done with it. A convert query is used to ask for a conversion between
 599  * one format and another.
 600  *
 601  * Free-function: gst_query_unref
 602  *
 603  * Returns: (transfer full): a #GstQuery
 604  */
 605 GstQuery *
 606 gst_query_new_convert (GstFormat src_format, gint64 value,
 607     GstFormat dest_format)
 608 {
 609   GstQuery *query;
 610   GstStructure *structure;
 611
 612   structure = gst_structure_id_new (GST_QUARK (QUERY_CONVERT),
 613       GST_QUARK (SRC_FORMAT), GST_TYPE_FORMAT, src_format,
 614       GST_QUARK (SRC_VALUE), G_TYPE_INT64, value,
 615       GST_QUARK (DEST_FORMAT), GST_TYPE_FORMAT, dest_format,
 616       GST_QUARK (DEST_VALUE), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
 617
 618   query = gst_query_new (GST_QUERY_CONVERT, structure);
 619
 620   return query;
 621 }
 622
 623 /**
 624  * gst_query_set_convert:
 625  * @query: a #GstQuery
 626  * @src_format: the source #GstFormat
 627  * @src_value: the source value
 628  * @dest_format: the destination #GstFormat
 629  * @dest_value: the destination value
 630  *
 631  * Answer a convert query by setting the requested values.
 632  */
 633 void
 634 gst_query_set_convert (GstQuery * query, GstFormat src_format, gint64 src_value,
 635     GstFormat dest_format, gint64 dest_value)
 636 {
 637   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_CONVERT);
 638
 639   gst_structure_id_set (query->structure,
 640       GST_QUARK (SRC_FORMAT), GST_TYPE_FORMAT, src_format,
 641       GST_QUARK (SRC_VALUE), G_TYPE_INT64, src_value,
 642       GST_QUARK (DEST_FORMAT), GST_TYPE_FORMAT, dest_format,
 643       GST_QUARK (DEST_VALUE), G_TYPE_INT64, dest_value, NULL);
 644 }
 645
 646 /**
 647  * gst_query_parse_convert:
 648  * @query: a #GstQuery
 649  * @src_format: (out) (allow-none): the storage for the #GstFormat of the
 650  *     source value, or NULL
 651  * @src_value: (out) (allow-none): the storage for the source value, or NULL
 652  * @dest_format: (out) (allow-none): the storage for the #GstFormat of the
 653  *     destination value, or NULL
 654  * @dest_value: (out) (allow-none): the storage for the destination value,
 655  *     or NULL
 656  *
 657  * Parse a convert query answer. Any of @src_format, @src_value, @dest_format,
 658  * and @dest_value may be NULL, in which case that value is omitted.
 659  */
 660 void
 661 gst_query_parse_convert (GstQuery * query, GstFormat * src_format,
 662     gint64 * src_value, GstFormat * dest_format, gint64 * dest_value)
 663 {
 664   GstStructure *structure;
 665
 666   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_CONVERT);
 667
 668   structure = query->structure;
 669   if (src_format)
 670     *src_format = g_value_get_enum (gst_structure_id_get_value (structure,
 671             GST_QUARK (SRC_FORMAT)));
 672   if (src_value)
 673     *src_value = g_value_get_int64 (gst_structure_id_get_value (structure,
 674             GST_QUARK (SRC_VALUE)));
 675   if (dest_format)
 676     *dest_format = g_value_get_enum (gst_structure_id_get_value (structure,
 677             GST_QUARK (DEST_FORMAT)));
 678   if (dest_value)
 679     *dest_value = g_value_get_int64 (gst_structure_id_get_value (structure,
 680             GST_QUARK (DEST_VALUE)));
 681 }
 682
 683 /**
 684  * gst_query_new_segment:
 685  * @format: the #GstFormat for the new query
 686  *
 687  * Constructs a new segment query object. Use gst_query_unref()
 688  * when done with it. A segment query is used to discover information about the
 689  * currently configured segment for playback.
 690  *
 691  * Free-function: gst_query_unref
 692  *
 693  * Returns: (transfer full): a new #GstQuery
 694  */
 695 GstQuery *
 696 gst_query_new_segment (GstFormat format)
 697 {
 698   GstQuery *query;
 699   GstStructure *structure;
 700
 701   structure = gst_structure_id_new (GST_QUARK (QUERY_SEGMENT),
 702       GST_QUARK (RATE), G_TYPE_DOUBLE, (gdouble) 0.0,
 703       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 704       GST_QUARK (START_VALUE), G_TYPE_INT64, G_GINT64_CONSTANT (-1),
 705       GST_QUARK (STOP_VALUE), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
 706
 707   query = gst_query_new (GST_QUERY_SEGMENT, structure);
 708
 709   return query;
 710 }
 711
 712 /**
 713  * gst_query_set_segment:
 714  * @query: a #GstQuery
 715  * @rate: the rate of the segment
 716  * @format: the #GstFormat of the segment values (@start_value and @stop_value)
 717  * @start_value: the start value
 718  * @stop_value: the stop value
 719  *
 720  * Answer a segment query by setting the requested values. The normal
 721  * playback segment of a pipeline is 0 to duration at the default rate of
 722  * 1.0. If a seek was performed on the pipeline to play a different
 723  * segment, this query will return the range specified in the last seek.
 724  *
 725  * @start_value and @stop_value will respectively contain the configured
 726  * playback range start and stop values expressed in @format.
 727  * The values are always between 0 and the duration of the media and
 728  * @start_value <= @stop_value. @rate will contain the playback rate. For
 729  * negative rates, playback will actually happen from @stop_value to
 730  * @start_value.
 731  */
 732 void
 733 gst_query_set_segment (GstQuery * query, gdouble rate, GstFormat format,
 734     gint64 start_value, gint64 stop_value)
 735 {
 736   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_SEGMENT);
 737
 738   gst_structure_id_set (query->structure,
 739       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
 740       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 741       GST_QUARK (START_VALUE), G_TYPE_INT64, start_value,
 742       GST_QUARK (STOP_VALUE), G_TYPE_INT64, stop_value, NULL);
 743 }
 744
 745 /**
 746  * gst_query_parse_segment:
 747  * @query: a #GstQuery
 748  * @rate: (out) (allow-none): the storage for the rate of the segment, or NULL
 749  * @format: (out) (allow-none): the storage for the #GstFormat of the values,
 750  *     or NULL
 751  * @start_value: (out) (allow-none): the storage for the start value, or NULL
 752  * @stop_value: (out) (allow-none): the storage for the stop value, or NULL
 753  *
 754  * Parse a segment query answer. Any of @rate, @format, @start_value, and
 755  * @stop_value may be NULL, which will cause this value to be omitted.
 756  *
 757  * See gst_query_set_segment() for an explanation of the function arguments.
 758  */
 759 void
 760 gst_query_parse_segment (GstQuery * query, gdouble * rate, GstFormat * format,
 761     gint64 * start_value, gint64 * stop_value)
 762 {
 763   GstStructure *structure;
 764
 765   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_SEGMENT);
 766
 767   structure = query->structure;
 768   if (rate)
 769     *rate = g_value_get_double (gst_structure_id_get_value (structure,
 770             GST_QUARK (RATE)));
 771   if (format)
 772     *format = g_value_get_enum (gst_structure_id_get_value (structure,
 773             GST_QUARK (FORMAT)));
 774   if (start_value)
 775     *start_value = g_value_get_int64 (gst_structure_id_get_value (structure,
 776             GST_QUARK (START_VALUE)));
 777   if (stop_value)
 778     *stop_value = g_value_get_int64 (gst_structure_id_get_value (structure,
 779             GST_QUARK (STOP_VALUE)));
 780 }
 781
 782 /**
 783  * gst_query_new_application:
 784  * @type: the query type
 785  * @structure: a structure for the query
 786  *
 787  * Constructs a new custom application query object. Use gst_query_unref()
 788  * when done with it.
 789  *
 790  * Free-function: gst_query_unref
 791  *
 792  * Returns: (transfer full): a new #GstQuery
 793  */
 794 GstQuery *
 795 gst_query_new_application (GstQueryType type, GstStructure * structure)
 796 {
 797   g_return_val_if_fail (gst_query_type_get_details (type) != NULL, NULL);
 798   g_return_val_if_fail (structure != NULL, NULL);
 799
 800   return gst_query_new (type, structure);
 801 }
 802
 803 /**
 804  * gst_query_get_structure:
 805  * @query: a #GstQuery
 806  *
 807  * Get the structure of a query.
 808  *
 809  * Returns: (transfer none): the #GstStructure of the query. The structure is
 810  *     still owned by the query and will therefore be freed when the query
 811  *     is unreffed.
 812  */
 813 GstStructure *
 814 gst_query_get_structure (GstQuery * query)
 815 {
 816   g_return_val_if_fail (GST_IS_QUERY (query), NULL);
 817
 818   return query->structure;
 819 }
 820
 821 /**
 822  * gst_query_new_seeking:
 823  * @format: the default #GstFormat for the new query
 824  *
 825  * Constructs a new query object for querying seeking properties of
 826  * the stream.
 827  *
 828  * Free-function: gst_query_unref
 829  *
 830  * Returns: (transfer full): a new #GstQuery
 831  */
 832 GstQuery *
 833 gst_query_new_seeking (GstFormat format)
 834 {
 835   GstQuery *query;
 836   GstStructure *structure;
 837
 838   structure = gst_structure_id_new (GST_QUARK (QUERY_SEEKING),
 839       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 840       GST_QUARK (SEEKABLE), G_TYPE_BOOLEAN, FALSE,
 841       GST_QUARK (SEGMENT_START), G_TYPE_INT64, G_GINT64_CONSTANT (-1),
 842       GST_QUARK (SEGMENT_END), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
 843
 844   query = gst_query_new (GST_QUERY_SEEKING, structure);
 845
 846   return query;
 847 }
 848
 849 /**
 850  * gst_query_set_seeking:
 851  * @query: a #GstQuery
 852  * @format: the format to set for the @segment_start and @segment_end values
 853  * @seekable: the seekable flag to set
 854  * @segment_start: the segment_start to set
 855  * @segment_end: the segment_end to set
 856  *
 857  * Set the seeking query result fields in @query.
 858  */
 859 void
 860 gst_query_set_seeking (GstQuery * query, GstFormat format,
 861     gboolean seekable, gint64 segment_start, gint64 segment_end)
 862 {
 863   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_SEEKING);
 864
 865   gst_structure_id_set (query->structure,
 866       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 867       GST_QUARK (SEEKABLE), G_TYPE_BOOLEAN, seekable,
 868       GST_QUARK (SEGMENT_START), G_TYPE_INT64, segment_start,
 869       GST_QUARK (SEGMENT_END), G_TYPE_INT64, segment_end, NULL);
 870 }
 871
 872 /**
 873  * gst_query_parse_seeking:
 874  * @query: a GST_QUERY_SEEKING type query #GstQuery
 875  * @format: (out) (allow-none): the format to set for the @segment_start
 876  *     and @segment_end values, or NULL
 877  * @seekable: (out) (allow-none): the seekable flag to set, or NULL
 878  * @segment_start: (out) (allow-none): the segment_start to set, or NULL
 879  * @segment_end: (out) (allow-none): the segment_end to set, or NULL
 880  *
 881  * Parse a seeking query, writing the format into @format, and
 882  * other results into the passed parameters, if the respective parameters
 883  * are non-NULL
 884  */
 885 void
 886 gst_query_parse_seeking (GstQuery * query, GstFormat * format,
 887     gboolean * seekable, gint64 * segment_start, gint64 * segment_end)
 888 {
 889   GstStructure *structure;
 890
 891   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_SEEKING);
 892
 893   structure = query->structure;
 894   if (format)
 895     *format = g_value_get_enum (gst_structure_id_get_value (structure,
 896             GST_QUARK (FORMAT)));
 897   if (seekable)
 898     *seekable = g_value_get_boolean (gst_structure_id_get_value (structure,
 899             GST_QUARK (SEEKABLE)));
 900   if (segment_start)
 901     *segment_start = g_value_get_int64 (gst_structure_id_get_value (structure,
 902             GST_QUARK (SEGMENT_START)));
 903   if (segment_end)
 904     *segment_end = g_value_get_int64 (gst_structure_id_get_value (structure,
 905             GST_QUARK (SEGMENT_END)));
 906 }
 907
 908 /**
 909  * gst_query_new_formats:
 910  *
 911  * Constructs a new query object for querying formats of
 912  * the stream.
 913  *
 914  * Free-function: gst_query_unref
 915  *
 916  * Returns: (transfer full): a new #GstQuery
 917  *
 918  * Since: 0.10.4
 919  */
 920 GstQuery *
 921 gst_query_new_formats (void)
 922 {
 923   GstQuery *query;
 924   GstStructure *structure;
 925
 926   structure = gst_structure_id_empty_new (GST_QUARK (QUERY_FORMATS));
 927   query = gst_query_new (GST_QUERY_FORMATS, structure);
 928
 929   return query;
 930 }
 931
 932 static void
 933 gst_query_list_add_format (GValue * list, GstFormat format)
 934 {
 935   GValue item = { 0, };
 936
 937   g_value_init (&item, GST_TYPE_FORMAT);
 938   g_value_set_enum (&item, format);
 939   gst_value_list_append_value (list, &item);
 940   g_value_unset (&item);
 941 }
 942
 943 /**
 944  * gst_query_set_formats:
 945  * @query: a #GstQuery
 946  * @n_formats: the number of formats to set.
 947  * @...: A number of @GstFormats equal to @n_formats.
 948  *
 949  * Set the formats query result fields in @query. The number of formats passed
 950  * must be equal to @n_formats.
 951  */
 952 void
 953 gst_query_set_formats (GstQuery * query, gint n_formats, ...)
 954 {
 955   va_list ap;
 956   GValue list = { 0, };
 957   gint i;
 958
 959   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_FORMATS);
 960
 961   g_value_init (&list, GST_TYPE_LIST);
 962
 963   va_start (ap, n_formats);
 964   for (i = 0; i < n_formats; i++) {
 965     gst_query_list_add_format (&list, va_arg (ap, GstFormat));
 966   }
 967   va_end (ap);
 968
 969   gst_structure_set_value (query->structure, "formats", &list);
 970
 971   g_value_unset (&list);
 972
 973 }
 974
 975 /**
 976  * gst_query_set_formatsv:
 977  * @query: a #GstQuery
 978  * @n_formats: the number of formats to set.
 979  * @formats: (in) (array length=n_formats): an array containing @n_formats
 980  *     @GstFormat values.
 981  *
 982  * Set the formats query result fields in @query. The number of formats passed
 983  * in the @formats array must be equal to @n_formats.
 984  *
 985  * Since: 0.10.4
 986  */
 987 void
 988 gst_query_set_formatsv (GstQuery * query, gint n_formats,
 989     const GstFormat * formats)
 990 {
 991   GValue list = { 0, };
 992   gint i;
 993
 994   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_FORMATS);
 995
 996   g_value_init (&list, GST_TYPE_LIST);
 997   for (i = 0; i < n_formats; i++) {
 998     gst_query_list_add_format (&list, formats[i]);
 999   }
1000   gst_structure_set_value (query->structure, "formats", &list);
1001
1002   g_value_unset (&list);
1003 }
1004
1005 /**
1006  * gst_query_parse_formats_length:
1007  * @query: a #GstQuery
1008  * @n_formats: (out): the number of formats in this query.
1009  *
1010  * Parse the number of formats in the formats @query.
1011  *
1012  * Since: 0.10.4
1013  */
1014 void
1015 gst_query_parse_formats_length (GstQuery * query, guint * n_formats)
1016 {
1017   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_FORMATS);
1018
1019   if (n_formats) {
1020     const GValue *list;
1021
1022     list = gst_structure_get_value (query->structure, "formats");
1023     if (list == NULL)
1024       *n_formats = 0;
1025     else
1026       *n_formats = gst_value_list_get_size (list);
1027   }
1028 }
1029
1030 /**
1031  * gst_query_parse_formats_nth:
1032  * @query: a #GstQuery
1033  * @nth: (out): the nth format to retrieve.
1034  * @format: (out): a pointer to store the nth format
1035  *
1036  * Parse the format query and retrieve the @nth format from it into
1037  * @format. If the list contains less elements than @nth, @format will be
1038  * set to GST_FORMAT_UNDEFINED.
1039  *
1040  * Since: 0.10.4
1041  */
1042 void
1043 gst_query_parse_formats_nth (GstQuery * query, guint nth, GstFormat * format)
1044 {
1045   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_FORMATS);
1046
1047   if (format) {
1048     const GValue *list;
1049
1050     list = gst_structure_get_value (query->structure, "formats");
1051     if (list == NULL) {
1052       *format = GST_FORMAT_UNDEFINED;
1053     } else {
1054       if (nth < gst_value_list_get_size (list)) {
1055         *format = g_value_get_enum (gst_value_list_get_value (list, nth));
1056       } else
1057         *format = GST_FORMAT_UNDEFINED;
1058     }
1059   }
1060 }
1061
1062 /**
1063  * gst_query_new_buffering
1064  * @format: the default #GstFormat for the new query
1065  *
1066  * Constructs a new query object for querying the buffering status of
1067  * a stream.
1068  *
1069  * Free-function: gst_query_new
1070  *
1071  * Returns: (transfer full): a new #GstQuery
1072  *
1073  * Since: 0.10.20
1074  */
1075 GstQuery *
1076 gst_query_new_buffering (GstFormat format)
1077 {
1078   GstQuery *query;
1079   GstStructure *structure;
1080
1081   /* by default, we configure the answer as no buffering with a 100% buffering
1082    * progress */
1083   structure = gst_structure_id_new (GST_QUARK (QUERY_BUFFERING),
1084       GST_QUARK (BUSY), G_TYPE_BOOLEAN, FALSE,
1085       GST_QUARK (BUFFER_PERCENT), G_TYPE_INT, 100,
1086       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, GST_BUFFERING_STREAM,
1087       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, -1,
1088       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, -1,
1089       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, G_GINT64_CONSTANT (0),
1090       GST_QUARK (ESTIMATED_TOTAL), G_TYPE_INT64, G_GINT64_CONSTANT (-1),
1091       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1092       GST_QUARK (START_VALUE), G_TYPE_INT64, G_GINT64_CONSTANT (-1),
1093       GST_QUARK (STOP_VALUE), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
1094
1095   query = gst_query_new (GST_QUERY_BUFFERING, structure);
1096
1097   return query;
1098 }
1099
1100 /**
1101  * gst_query_set_buffering_percent
1102  * @query: A valid #GstQuery of type GST_QUERY_BUFFERING.
1103  * @busy: if buffering is busy
1104  * @percent: a buffering percent
1105  *
1106  * Set the percentage of buffered data. This is a value between 0 and 100.
1107  * The @busy indicator is %TRUE when the buffering is in progress.
1108  *
1109  * Since: 0.10.20
1110  */
1111 void
1112 gst_query_set_buffering_percent (GstQuery * query, gboolean busy, gint percent)
1113 {
1114   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING);
1115   g_return_if_fail (percent >= 0 && percent <= 100);
1116
1117   gst_structure_id_set (query->structure,
1118       GST_QUARK (BUSY), G_TYPE_BOOLEAN, busy,
1119       GST_QUARK (BUFFER_PERCENT), G_TYPE_INT, percent, NULL);
1120 }
1121
1122 /**
1123  * gst_query_parse_buffering_percent
1124  * @query: A valid #GstQuery of type GST_QUERY_BUFFERING.
1125  * @busy: (out) (allow-none): if buffering is busy, or NULL
1126  * @percent: (out) (allow-none): a buffering percent, or NULL
1127  *
1128  * Get the percentage of buffered data. This is a value between 0 and 100.
1129  * The @busy indicator is %TRUE when the buffering is in progress.
1130  *
1131  * Since: 0.10.20
1132  */
1133 void
1134 gst_query_parse_buffering_percent (GstQuery * query, gboolean * busy,
1135     gint * percent)
1136 {
1137   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING);
1138
1139   if (busy)
1140     *busy = g_value_get_boolean (gst_structure_id_get_value (query->structure,
1141             GST_QUARK (BUSY)));
1142   if (percent)
1143     *percent = g_value_get_int (gst_structure_id_get_value (query->structure,
1144             GST_QUARK (BUFFER_PERCENT)));
1145 }
1146
1147 /**
1148  * gst_query_set_buffering_stats:
1149  * @query: A valid #GstQuery of type GST_QUERY_BUFFERING.
1150  * @mode: a buffering mode
1151  * @avg_in: the average input rate
1152  * @avg_out: the average output rate
1153  * @buffering_left: amount of buffering time left
1154  *
1155  * Configures the buffering stats values in @query.
1156  *
1157  * Since: 0.10.20
1158  */
1159 void
1160 gst_query_set_buffering_stats (GstQuery * query, GstBufferingMode mode,
1161     gint avg_in, gint avg_out, gint64 buffering_left)
1162 {
1163   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING);
1164
1165   gst_structure_id_set (query->structure,
1166       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, mode,
1167       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, avg_in,
1168       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, avg_out,
1169       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
1170 }
1171
1172 /**
1173  * gst_query_parse_buffering_stats:
1174  * @query: A valid #GstQuery of type GST_QUERY_BUFFERING.
1175  * @mode: (out) (allow-none): a buffering mode, or NULL
1176  * @avg_in: (out) (allow-none): the average input rate, or NULL
1177  * @avg_out: (out) (allow-none): the average output rat, or NULLe
1178  * @buffering_left: (out) (allow-none): amount of buffering time left, or NULL
1179  *
1180  * Extracts the buffering stats values from @query.
1181  *
1182  * Since: 0.10.20
1183  */
1184 void
1185 gst_query_parse_buffering_stats (GstQuery * query,
1186     GstBufferingMode * mode, gint * avg_in, gint * avg_out,
1187     gint64 * buffering_left)
1188 {
1189   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING);
1190
1191   if (mode)
1192     *mode = g_value_get_enum (gst_structure_id_get_value (query->structure,
1193             GST_QUARK (BUFFERING_MODE)));
1194   if (avg_in)
1195     *avg_in = g_value_get_int (gst_structure_id_get_value (query->structure,
1196             GST_QUARK (AVG_IN_RATE)));
1197   if (avg_out)
1198     *avg_out = g_value_get_int (gst_structure_id_get_value (query->structure,
1199             GST_QUARK (AVG_OUT_RATE)));
1200   if (buffering_left)
1201     *buffering_left =
1202         g_value_get_int64 (gst_structure_id_get_value (query->structure,
1203             GST_QUARK (BUFFERING_LEFT)));
1204 }
1205
1206
1207 /**
1208  * gst_query_set_buffering_range:
1209  * @query: a #GstQuery
1210  * @format: the format to set for the @start and @stop values
1211  * @start: the start to set
1212  * @stop: the stop to set
1213  * @estimated_total: estimated total amount of download time
1214  *
1215  * Set the available query result fields in @query.
1216  *
1217  * Since: 0.10.20
1218  */
1219 void
1220 gst_query_set_buffering_range (GstQuery * query, GstFormat format,
1221     gint64 start, gint64 stop, gint64 estimated_total)
1222 {
1223   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING);
1224
1225   gst_structure_id_set (query->structure,
1226       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1227       GST_QUARK (START_VALUE), G_TYPE_INT64, start,
1228       GST_QUARK (STOP_VALUE), G_TYPE_INT64, stop,
1229       GST_QUARK (ESTIMATED_TOTAL), G_TYPE_INT64, estimated_total, NULL);
1230 }
1231
1232 /**
1233  * gst_query_parse_buffering_range:
1234  * @query: a GST_QUERY_BUFFERING type query #GstQuery
1235  * @format: (out) (allow-none): the format to set for the @segment_start
1236  *     and @segment_end values, or NULL
1237  * @start: (out) (allow-none): the start to set, or NULL
1238  * @stop: (out) (allow-none): the stop to set, or NULL
1239  * @estimated_total: (out) (allow-none): estimated total amount of download
1240  *     time, or NULL
1241  *
1242  * Parse an available query, writing the format into @format, and
1243  * other results into the passed parameters, if the respective parameters
1244  * are non-NULL
1245  *
1246  * Since: 0.10.20
1247  */
1248 void
1249 gst_query_parse_buffering_range (GstQuery * query, GstFormat * format,
1250     gint64 * start, gint64 * stop, gint64 * estimated_total)
1251 {
1252   GstStructure *structure;
1253
1254   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING);
1255
1256   structure = query->structure;
1257   if (format)
1258     *format = g_value_get_enum (gst_structure_id_get_value (structure,
1259             GST_QUARK (FORMAT)));
1260   if (start)
1261     *start = g_value_get_int64 (gst_structure_id_get_value (structure,
1262             GST_QUARK (START_VALUE)));
1263   if (stop)
1264     *stop = g_value_get_int64 (gst_structure_id_get_value (structure,
1265             GST_QUARK (STOP_VALUE)));
1266   if (estimated_total)
1267     *estimated_total =
1268         g_value_get_int64 (gst_structure_id_get_value (structure,
1269             GST_QUARK (ESTIMATED_TOTAL)));
1270 }
1271
1272 /**
1273  * gst_query_add_buffering_range
1274  * @query: a GST_QUERY_BUFFERING type query #GstQuery
1275  * @start: start position of the range
1276  * @stop: stop position of the range
1277  *
1278  * Set the buffering-ranges array field in @query. The current last
1279  * start position of the array should be inferior to @start.
1280  *
1281  * Returns: a #gboolean indicating if the range was added or not.
1282  *
1283  * Since: 0.10.31
1284  */
1285 gboolean
1286 gst_query_add_buffering_range (GstQuery * query, gint64 start, gint64 stop)
1287 {
1288   GValueArray *array;
1289   GValue *last_array_value;
1290   const GValue *value;
1291   GValue range_value = { 0 };
1292
1293   g_return_val_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING, FALSE);
1294
1295   if (G_UNLIKELY (start >= stop))
1296     return FALSE;
1297
1298   value =
1299       gst_structure_id_get_value (query->structure,
1300       GST_QUARK (BUFFERING_RANGES));
1301   if (value) {
1302     array = (GValueArray *) g_value_get_boxed (value);
1303     last_array_value = g_value_array_get_nth (array, array->n_values - 1);
1304     if (G_UNLIKELY (start <= gst_value_get_int64_range_min (last_array_value)))
1305       return FALSE;
1306   } else {
1307     GValue new_array_val = { 0, };
1308
1309     array = g_value_array_new (0);
1310
1311     g_value_init (&new_array_val, G_TYPE_VALUE_ARRAY);
1312     g_value_take_boxed (&new_array_val, array);
1313
1314     /* set the value array only once, so we then modify (append to) the
1315      * existing value array owned by the GstStructure / the field's GValue */
1316     gst_structure_id_take_value (query->structure, GST_QUARK (BUFFERING_RANGES),
1317         &new_array_val);
1318   }
1319
1320   g_value_init (&range_value, GST_TYPE_INT64_RANGE);
1321   gst_value_set_int64_range (&range_value, start, stop);
1322   g_value_array_append (array, &range_value);
1323   /* skip the g_value_unset(&range_value) here, we know it's not needed */
1324
1325   return TRUE;
1326 }
1327
1328 /**
1329  * gst_query_get_n_buffering_ranges
1330  * @query: a GST_QUERY_BUFFERING type query #GstQuery
1331  *
1332  * Retrieve the number of values currently stored in the
1333  * buffered-ranges array of the query's structure.
1334  *
1335  * Returns: the range array size as a #guint.
1336  *
1337  * Since: 0.10.31
1338  */
1339 guint
1340 gst_query_get_n_buffering_ranges (GstQuery * query)
1341 {
1342   GValueArray *array;
1343   const GValue *value;
1344   guint size = 0;
1345
1346   g_return_val_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING, 0);
1347
1348   value =
1349       gst_structure_id_get_value (query->structure,
1350       GST_QUARK (BUFFERING_RANGES));
1351   if (value) {
1352     array = (GValueArray *) g_value_get_boxed (value);
1353     size = array->n_values;
1354   }
1355   return size;
1356 }
1357
1358
1359 /**
1360  * gst_query_parse_nth_buffering_range
1361  * @query: a GST_QUERY_BUFFERING type query #GstQuery
1362  * @index: position in the buffered-ranges array to read
1363  * @start: (out) (allow-none): the start position to set, or NULL
1364  * @stop: (out) (allow-none): the stop position to set, or NULL
1365  *
1366  * Parse an available query and get the start and stop values stored
1367  * at the @index of the buffered ranges array.
1368  *
1369  * Returns: a #gboolean indicating if the parsing succeeded.
1370  *
1371  * Since: 0.10.31
1372  */
1373 gboolean
1374 gst_query_parse_nth_buffering_range (GstQuery * query, guint index,
1375     gint64 * start, gint64 * stop)
1376 {
1377   const GValue *value;
1378   GValueArray *ranges;
1379   GValue *range_value;
1380   gboolean ret = FALSE;
1381
1382   g_return_val_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_BUFFERING, ret);
1383
1384   value =
1385       gst_structure_id_get_value (query->structure,
1386       GST_QUARK (BUFFERING_RANGES));
1387   ranges = (GValueArray *) g_value_get_boxed (value);
1388   range_value = g_value_array_get_nth (ranges, index);
1389   if (range_value) {
1390     if (start)
1391       *start = gst_value_get_int64_range_min (range_value);
1392     if (stop)
1393       *stop = gst_value_get_int64_range_max (range_value);
1394     ret = TRUE;
1395   }
1396
1397   return ret;
1398 }
1399
1400
1401 /**
1402  * gst_query_new_uri:
1403  *
1404  * Constructs a new query URI query object. Use gst_query_unref()
1405  * when done with it. An URI query is used to query the current URI
1406  * that is used by the source or sink.
1407  *
1408  * Free-function: gst_query_unref
1409  *
1410  * Returns: (transfer full): a new #GstQuery
1411  *
1412  * Since: 0.10.22
1413  */
1414 GstQuery *
1415 gst_query_new_uri (void)
1416 {
1417   GstQuery *query;
1418   GstStructure *structure;
1419
1420   structure = gst_structure_id_new (GST_QUARK (QUERY_URI),
1421       GST_QUARK (URI), G_TYPE_STRING, NULL, NULL);
1422
1423   query = gst_query_new (GST_QUERY_URI, structure);
1424
1425   return query;
1426 }
1427
1428 /**
1429  * gst_query_set_uri:
1430  * @query: a #GstQuery with query type GST_QUERY_URI
1431  * @uri: the URI to set
1432  *
1433  * Answer a URI query by setting the requested URI.
1434  *
1435  * Since: 0.10.22
1436  */
1437 void
1438 gst_query_set_uri (GstQuery * query, const gchar * uri)
1439 {
1440   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_URI);
1441   g_return_if_fail (gst_uri_is_valid (uri));
1442
1443   gst_structure_id_set (query->structure, GST_QUARK (URI), G_TYPE_STRING, uri,
1444       NULL);
1445 }
1446
1447 /**
1448  * gst_query_parse_uri:
1449  * @query: a #GstQuery
1450  * @uri: (out callee-allocates) (allow-none): the storage for the current URI
1451  *     (may be NULL)
1452  *
1453  * Parse an URI query, writing the URI into @uri as a newly
1454  * allocated string, if the respective parameters are non-NULL.
1455  * Free the string with g_free() after usage.
1456  *
1457  * Since: 0.10.22
1458  */
1459 void
1460 gst_query_parse_uri (GstQuery * query, gchar ** uri)
1461 {
1462   g_return_if_fail (GST_QUERY_TYPE (query) == GST_QUERY_URI);
1463
1464   if (uri)
1465     *uri = g_value_dup_string (gst_structure_id_get_value (query->structure,
1466             GST_QUARK (URI)));
1467 }