## GstQuery

GstQuery — Dynamically register new query types. Provide functions to create queries, and to set and parse values in them.

## Synopsis

    #include <gst/gst.h>

                        GstQuery;
    enum                GstQueryType;
    #define             GST_QUERY_TYPE                      (query)
    #define             GST_QUERY_TYPE_NAME                 (query)
                        GstQueryTypeDefinition;
    const gchar*        gst_query_type_get_name             (GstQueryType query);
    GQuark              gst_query_type_to_quark             (GstQueryType query);
    GstQueryType        gst_query_type_register             (const gchar *nick,
                                                             const gchar *description);
    GstQueryType        gst_query_type_get_by_nick          (const gchar *nick);
    gboolean            gst_query_types_contains            (const GstQueryType *types,
                                                             GstQueryType type);
    const GstQueryTypeDefinition* gst_query_type_get_details
                                                            (GstQueryType type);
    GstIterator*        gst_query_type_iterate_definitions  (void);
    #define             gst_query_ref                       (q)
    #define             gst_query_unref                     (q)
    #define             gst_query_copy                      (q)
    #define             gst_query_make_writable             (q)
    GstQuery*           gst_query_new_application           (GstQueryType type,
                                                             GstStructure *structure);
    GstStructure*       gst_query_get_structure             (GstQuery *query);
    GstQuery*           gst_query_new_convert               (GstFormat src_format,
                                                             gint64 value,
                                                             GstFormat dest_format);
    void                gst_query_set_convert               (GstQuery *query,
                                                             GstFormat src_format,
                                                             gint64 src_value,
                                                             GstFormat dest_format,
                                                             gint64 dest_value);
    void                gst_query_parse_convert             (GstQuery *query,
                                                             GstFormat *src_format,
                                                             gint64 *src_value,
                                                             GstFormat *dest_format,
                                                             gint64 *dest_value);
    GstQuery*           gst_query_new_position              (GstFormat format);
    void                gst_query_set_position              (GstQuery *query,
                                                             GstFormat format,
                                                             gint64 cur);
    void                gst_query_parse_position            (GstQuery *query,
                                                             GstFormat *format,
                                                             gint64 *cur);
    GstQuery*           gst_query_new_duration              (GstFormat format);
    void                gst_query_set_duration              (GstQuery *query,
                                                             GstFormat format,
                                                             gint64 duration);
    void                gst_query_parse_duration            (GstQuery *query,
                                                             GstFormat *format,
                                                             gint64 *duration);
    GstQuery*           gst_query_new_latency               (void);
    void                gst_query_parse_latency             (GstQuery *query,
                                                             gboolean *live,
                                                             GstClockTime *min_latency,
                                                             GstClockTime *max_latency);
    void                gst_query_set_latency               (GstQuery *query,
                                                             gboolean live,
                                                             GstClockTime min_latency,
                                                             GstClockTime max_latency);
    GstQuery*           gst_query_new_seeking               (GstFormat format);
    void                gst_query_set_seeking               (GstQuery *query,
                                                             GstFormat format,
                                                             gboolean seekable,
                                                             gint64 segment_start,
                                                             gint64 segment_end);
    void                gst_query_parse_seeking             (GstQuery *query,
                                                             GstFormat *format,
                                                             gboolean *seekable,
                                                             gint64 *segment_start,
                                                             gint64 *segment_end);
    GstQuery*           gst_query_new_formats               (void);
    void                gst_query_set_formats               (GstQuery *query,
                                                             gint n_formats,
                                                             ...);
    void                gst_query_set_formatsv              (GstQuery *query,
                                                             gint n_formats,
                                                             GstFormat *formats);
    void                gst_query_parse_formats_length      (GstQuery *query,
                                                             guint *n_formats);
    void                gst_query_parse_formats_nth         (GstQuery *query,
                                                             guint nth,
                                                             GstFormat *format);
    GstQuery*           gst_query_new_segment               (GstFormat format);
    void                gst_query_set_segment               (GstQuery *query,
                                                             gdouble rate,
                                                             GstFormat format,
                                                             gint64 start_value,
                                                             gint64 stop_value);
    void                gst_query_parse_segment             (GstQuery *query,
                                                             gdouble *rate,
                                                             GstFormat *format,
                                                             gint64 *start_value,
                                                             gint64 *stop_value);

## Description

GstQuery functions are used to register a new query types to the gstreamer core. Query types can be used to perform queries on pads and elements.

Queries can be created using the `gst_query_new_xxx()` functions. Query values can be set using `gst_query_set_xxx()`, and parsed using `gst_query_parse_xxx()` helpers.

The following example shows how to query the duration of a pipeline:

Example 13. Query duration on a pipeline

     GstQuery *query;
     gboolean res;
     query = gst_query_new_duration (GST_FORMAT_TIME);
     res = gst_element_query (pipeline, query);
     if (res) {
       gint64 duration;
       gst_query_parse_duration (query, NULL, &duration);
       g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
     }
     else {
       g_print ("duration query failed...");
     }
     gst_query_unref (query);

Last reviewed on 2006-02-14 (0.10.4)

## Details

### GstQuery

    typedef struct {
      GstMiniObject mini_object;

      GstQueryType type;

      GstStructure *structure;
    } GstQuery;

The GstQuery structure.

GstMiniObject `mini_object`; | The parent GstMiniObject type
GstQueryType `type`; | the GstQueryType
GstStructure *`structure`; | the GstStructure containing the query details.

### enum GstQueryType

    typedef enum {
      GST_QUERY_NONE = 0,
      GST_QUERY_POSITION,
      GST_QUERY_DURATION,
      GST_QUERY_LATENCY,
      GST_QUERY_JITTER, 	/* not in draft-query, necessary? */
      GST_QUERY_RATE,
      GST_QUERY_SEEKING,
      GST_QUERY_SEGMENT,
      GST_QUERY_CONVERT,
      GST_QUERY_FORMATS
    } GstQueryType;

Standard predefined Query types

`GST_QUERY_NONE` | invalid query type
`GST_QUERY_POSITION` | current position in stream
`GST_QUERY_DURATION` | total duration of the stream
`GST_QUERY_LATENCY` | latency of stream
`GST_QUERY_JITTER` | current jitter of stream
`GST_QUERY_RATE` | current rate of the stream
`GST_QUERY_SEEKING` | seeking capabilities
`GST_QUERY_SEGMENT` | segment start/stop positions
`GST_QUERY_CONVERT` | convert values between formats
`GST_QUERY_FORMATS` | query supported formats for convert

### GST_QUERY_TYPE()

    #define GST_QUERY_TYPE(query)  (((GstQuery*)(query))->type)

Get the GstQueryType of the query.

`query` : | the query to query

### GST_QUERY_TYPE_NAME()

    #define GST_QUERY_TYPE_NAME(query) (gst_query_type_get_name(GST_QUERY_TYPE(query)))

Get a constant string representation of the GstQueryType of the query.

`query` : | the query to query

Since 0.10.4

### GstQueryTypeDefinition

    typedef struct {
      GstQueryType   value;
      gchar  	*nick;
      gchar  	*description;
      GQuark         quark;
    } GstQueryTypeDefinition;

A Query Type definition

GstQueryType `value`; | the unique id of the Query type
gchar *`nick`; | a short nick
gchar *`description`; | a longer description of the query type
GQuark `quark`; | the quark for the nick

### gst_query_type_get_name ()

    const gchar*        gst_query_type_get_name             (GstQueryType query);

Get a printable name for the given query type. Do not modify or free.

`query` : | the query type
Returns : | a reference to the static name of the query.

### gst_query_type_to_quark ()

    GQuark              gst_query_type_to_quark             (GstQueryType query);

Get the unique quark for the given query type.

`query` : | the query type
Returns : | the quark associated with the query type

### gst_query_type_register ()

    GstQueryType        gst_query_type_register             (const gchar *nick,
                                                             const gchar *description);

Create a new GstQueryType based on the nick or return an already registered query with that nick

`nick` : | The nick of the new query
`description` : | The description of the new query
Returns : | A new GstQueryType or an already registered query with the same nick.

### gst_query_type_get_by_nick ()

    GstQueryType        gst_query_type_get_by_nick          (const gchar *nick);

Get the query type registered with `nick`.

`nick` : | The nick of the query
Returns : | The query registered with `nick` or GST_QUERY_NONE if the query was not registered.

### gst_query_types_contains ()

    gboolean            gst_query_types_contains            (const GstQueryType *types,
                                                             GstQueryType type);

See if the given GstQueryType is inside the `types` query types array.

`types` : | The query array to search
`type` : | the GstQueryType to find
Returns : | TRUE if the type is found inside the array

### gst_query_type_get_details ()

    const GstQueryTypeDefinition* gst_query_type_get_details
                                                            (GstQueryType type);

Get details about the given GstQueryType.

`type` : | a GstQueryType
Returns : | The GstQueryTypeDefinition for `type` or NULL on failure.

### gst_query_type_iterate_definitions ()

    GstIterator*        gst_query_type_iterate_definitions  (void);

Get a GstIterator of all the registered query types. The definitions iterated over are read only.

Returns : | A GstIterator of GstQueryTypeDefinition.

### gst_query_ref()

    #define         gst_query_ref(q)		GST_QUERY (gst_mini_object_ref (GST_MINI_OBJECT (q)))

Increases the refcount of the given query by one.

`q` : | a GstQuery to increase the refcount of.

### gst_query_unref()

    #define         gst_query_unref(q)		gst_mini_object_unref (GST_MINI_OBJECT (q))

Decreases the refcount of the query. If the refcount reaches 0, the query will be freed.

`q` : | a GstQuery to decrease the refcount of.

### gst_query_copy()

    #define         gst_query_copy(q)		GST_QUERY (gst_mini_object_copy (GST_MINI_OBJECT (q)))

Copies the given query using the copy function of the parent GstData structure.

`q` : | a GstQuery to copy.

### gst_query_make_writable()

    #define         gst_query_make_writable(q)	GST_QUERY (gst_mini_object_make_writable (GST_MINI_OBJECT (q)))

Makes a writable query from the given query.

`q` : | a GstQuery to make writable

### gst_query_new_application ()

    GstQuery*           gst_query_new_application           (GstQueryType type,
                                                             GstStructure *structure);

Constructs a new custom application query object. Use `gst_query_unref()` when done with it.

`type` : | the query type
`structure` : | a structure for the query
Returns : | a GstQuery

### gst_query_get_structure ()

    GstStructure*       gst_query_get_structure             (GstQuery *query);

Get the structure of a query.

`query` : | a GstQuery
Returns : | The GstStructure of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed.

### gst_query_new_convert ()

    GstQuery*           gst_query_new_convert               (GstFormat src_format,
                                                             gint64 value,
                                                             GstFormat dest_format);

Constructs a new convert query object. Use `gst_query_unref()` when done with it. A convert query is used to ask for a conversion between one format and another.

`src_format` : | the source GstFormat for the new query
`value` : | the value to convert
`dest_format` : | the target GstFormat
Returns : | A GstQuery

### gst_query_set_convert ()

    void                gst_query_set_convert               (GstQuery *query,
                                                             GstFormat src_format,
                                                             gint64 src_value,
                                                             GstFormat dest_format,
                                                             gint64 dest_value);

Answer a convert query by setting the requested values.

`query` : | a GstQuery
`src_format` : | the source GstFormat
`src_value` : | the source value
`dest_format` : | the destination GstFormat
`dest_value` : | the destination value

### gst_query_parse_convert ()

    void                gst_query_parse_convert             (GstQuery *query,
                                                             GstFormat *src_format,
                                                             gint64 *src_value,
                                                             GstFormat *dest_format,
                                                             gint64 *dest_value);

Parse a convert query answer. Any of `src_format`, `src_value`, `dest_format`, and `dest_value` may be NULL, in which case that value is omitted.

`query` : | a GstQuery
`src_format` : | the storage for the GstFormat of the source value, or NULL
`src_value` : | the storage for the source value, or NULL
`dest_format` : | the storage for the GstFormat of the destination value, or NULL
`dest_value` : | the storage for the destination value, or NULL

### gst_query_new_position ()

    GstQuery*           gst_query_new_position              (GstFormat format);

Constructs a new query stream position query object. Use `gst_query_unref()` when done with it. A position query is used to query the current position of playback in the streams, in some format.

`format` : | the default GstFormat for the new query
Returns : | A GstQuery

### gst_query_set_position ()

    void                gst_query_set_position              (GstQuery *query,
                                                             GstFormat format,
                                                             gint64 cur);

Answer a position query by setting the requested value in the given format.

`query` : | a GstQuery with query type GST_QUERY_POSITION
`format` : | the requested GstFormat
`cur` : | the position to set

### gst_query_parse_position ()

    void                gst_query_parse_position            (GstQuery *query,
                                                             GstFormat *format,
                                                             gint64 *cur);

Parse a position query, writing the format into `format`, and the position into `cur`, if the respective parameters are non-NULL.

`query` : | a GstQuery
`format` : | the storage for the GstFormat of the position values (may be NULL)
`cur` : | the storage for the current position (may be NULL)

### gst_query_new_duration ()

    GstQuery*           gst_query_new_duration              (GstFormat format);

Constructs a new stream duration query object to query in the given format. Use `gst_query_unref()` when done with it. A duration query will give the total length of the stream.

`format` : | the GstFormat for this duration query
Returns : | A GstQuery

### gst_query_set_duration ()

    void                gst_query_set_duration              (GstQuery *query,
                                                             GstFormat format,
                                                             gint64 duration);

Answer a duration query by setting the requested value in the given format.

`query` : | a GstQuery
`format` : | the GstFormat for the duration
`duration` : | the duration of the stream

### gst_query_parse_duration ()

    void                gst_query_parse_duration            (GstQuery *query,
                                                             GstFormat *format,
                                                             gint64 *duration);

Parse a duration query answer. Write the format of the duration into `format`, and the value into `duration`, if the respective variables are non-NULL.

`query` : | a GstQuery
`format` : | the storage for the GstFormat of the duration value, or NULL.
`duration` : | the storage for the total duration, or NULL.

### gst_query_new_latency ()

    GstQuery*           gst_query_new_latency               (void);

Constructs a new latency query object. Use `gst_query_unref()` when done with it. A latency query is usually performed by sinks to compensate for additional latency introduced by elements in the pipeline.

Returns : | A GstQuery

Since 0.10.12

### gst_query_parse_latency ()

    void                gst_query_parse_latency             (GstQuery *query,
                                                             gboolean *live,
                                                             GstClockTime *min_latency,
                                                             GstClockTime *max_latency);

Parse a latency query answer.

`query` : | a GstQuery
`live` : | storage for live or NULL
`min_latency` : | the storage for the min latency or NULL
`max_latency` : | the storage for the max latency or NULL

Since 0.10.12

### gst_query_set_latency ()

    void                gst_query_set_latency               (GstQuery *query,
                                                             gboolean live,
                                                             GstClockTime min_latency,
                                                             GstClockTime max_latency);

Answer a latency query by setting the requested values in the given format.

`query` : | a GstQuery
`live` : | if there is a live element upstream
`min_latency` : | the minimal latency of the live element
`max_latency` : | the maximal latency of the live element

Since 0.10.12

### gst_query_new_seeking ()

    GstQuery*           gst_query_new_seeking               (GstFormat format);

Constructs a new query object for querying seeking properties of the stream.

`format` : | the default GstFormat for the new query
Returns : | A GstQuery

### gst_query_set_seeking ()

    void                gst_query_set_seeking               (GstQuery *query,
                                                             GstFormat format,
                                                             gboolean seekable,
                                                             gint64 segment_start,
                                                             gint64 segment_end);

Set the seeking query result fields in `query`.

`query` : | a GstQuery
`format` : | the format to set for the `segment_start` and `segment_end` values
`seekable` : | the seekable flag to set
`segment_start` : | the segment_start to set
`segment_end` : | the segment_end to set

### gst_query_parse_seeking ()

    void                gst_query_parse_seeking             (GstQuery *query,
                                                             GstFormat *format,
                                                             gboolean *seekable,
                                                             gint64 *segment_start,
                                                             gint64 *segment_end);

Parse a seeking query, writing the format into `format`, and other results into the passed parameters, if the respective parameters are non-NULL

`query` : | a GST_QUERY_SEEKING type query GstQuery
`format` : | the format to set for the `segment_start` and `segment_end` values
`seekable` : | the seekable flag to set
`segment_start` : | the segment_start to set
`segment_end` : | the segment_end to set

### gst_query_new_formats ()

    GstQuery*           gst_query_new_formats               (void);

Constructs a new query object for querying formats of the stream.

Returns : | A GstQuery

Since 0.10.4

### gst_query_set_formats ()

    void                gst_query_set_formats               (GstQuery *query,
                                                             gint n_formats,
                                                             ...);

Set the formats query result fields in `query`. The number of formats passed must be equal to `n_formats`.

`query` : | a GstQuery
`n_formats` : | the number of formats to set.
`...` : | A number of `GstFormats` equal to `n_formats`.

### gst_query_set_formatsv ()

    void                gst_query_set_formatsv              (GstQuery *query,
                                                             gint n_formats,
                                                             GstFormat *formats);

Set the formats query result fields in `query`. The number of formats passed in the `formats` array must be equal to `n_formats`.

`query` : | a GstQuery
`n_formats` : | the number of formats to set.
`formats` : | An array containing `n_formats` `GstFormat` values.

Since 0.10.4

### gst_query_parse_formats_length ()

    void                gst_query_parse_formats_length      (GstQuery *query,
                                                             guint *n_formats);

Parse the number of formats in the formats `query`.

`query` : | a GstQuery
`n_formats` : | the number of formats in this query.

Since 0.10.4

### gst_query_parse_formats_nth ()

    void                gst_query_parse_formats_nth         (GstQuery *query,
                                                             guint nth,
                                                             GstFormat *format);

Parse the format query and retrieve the `nth` format from it into `format`. If the list contains less elements than `nth`, `format` will be set to GST_FORMAT_UNDEFINED.

`query` : | a GstQuery
`nth` : | the nth format to retrieve.
`format` : | a pointer to store the nth format

Since 0.10.4

### gst_query_new_segment ()

    GstQuery*           gst_query_new_segment               (GstFormat format);

Constructs a new segment query object. Use `gst_query_unref()` when done with it. A segment query is used to discover information about the currently configured segment for playback.

`format` : | the GstFormat for the new query
Returns : | a GstQuery

### gst_query_set_segment ()

    void                gst_query_set_segment               (GstQuery *query,
                                                             gdouble rate,
                                                             GstFormat format,
                                                             gint64 start_value,
                                                             gint64 stop_value);

Answer a segment query by setting the requested values. The normal playback segment of a pipeline is 0 to duration at the default rate of 1.0. If a seek was performed on the pipeline to play a different segment, this query will return the range specified in the last seek.

`start_value` and `stop_value` will respectively contain the configured playback range start and stop values expressed in `format`. The values are always between 0 and the duration of the media and `start_value` <= `stop_value`. `rate` will contain the playback rate. For negative rates, playback will actually happen from `stop_value` to `start_value`.

`query` : | a GstQuery
`rate` : | the rate of the segment
`format` : | the GstFormat of the segment values (`start_value` and `stop_value`)
`start_value` : | the start value
`stop_value` : | the stop value

### gst_query_parse_segment ()

    void                gst_query_parse_segment             (GstQuery *query,
                                                             gdouble *rate,
                                                             GstFormat *format,
                                                             gint64 *start_value,
                                                             gint64 *stop_value);

Parse a segment query answer. Any of `rate`, `format`, `start_value`, and `stop_value` may be NULL, which will cause this value to be omitted.

See `gst_query_set_segment()` for an explanation of the function arguments.

`query` : | a GstQuery
`rate` : | the storage for the rate of the segment, or NULL
`format` : | the storage for the GstFormat of the values, or NULL
`start_value` : | the storage for the start value, or NULL
`stop_value` : | the storage for the stop value, or NULL

## See Also

GstPad, GstElement