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