|  |  |  | GStreamer 0.10 Core Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | ||||
| GstQueryGstQuery — Dynamically register new query types. Provide functions to create queries, and to set and parse values in them. | 
#include <gst/gst.h>
                    GstQuery;
enum                GstQueryType;
#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);
GstQuery *          gst_query_ref                       (GstQuery *q);
void                gst_query_unref                     (GstQuery *q);
GstQuery *          gst_query_copy                      (const GstQuery *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);
enum                GstBufferingMode;
GstQuery*           gst_query_new_buffering             (GstFormat format);
void                gst_query_set_buffering_percent     (GstQuery *query,
                                                         gboolean busy,
                                                         gint percent);
void                gst_query_parse_buffering_percent   (GstQuery *query,
                                                         gboolean *busy,
                                                         gint *percent);
void                gst_query_set_buffering_stats       (GstQuery *query,
                                                         GstBufferingMode mode,
                                                         gint avg_in,
                                                         gint avg_out,
                                                         gint64 buffering_left);
void                gst_query_parse_buffering_stats     (GstQuery *query,
                                                         GstBufferingMode *mode,
                                                         gint *avg_in,
                                                         gint *avg_out,
                                                         gint64 *buffering_left);
void                gst_query_set_buffering_range       (GstQuery *query,
                                                         GstFormat format,
                                                         gint64 start,
                                                         gint64 stop,
                                                         gint64 estimated_total);
void                gst_query_parse_buffering_range     (GstQuery *query,
                                                         GstFormat *format,
                                                         gint64 *start,
                                                         gint64 *stop,
                                                         gint64 *estimated_total);
gboolean            gst_query_add_buffering_range       (GstQuery *query,
                                                         gint64 start,
                                                         gint64 stop);
guint               gst_query_get_n_buffering_ranges    (GstQuery *query);
gboolean            gst_query_parse_nth_buffering_range (GstQuery *query,
                                                         guint index,
                                                         gint64 *start,
                                                         gint64 *stop);
GstQuery *          gst_query_new_uri                   (void);
void                gst_query_parse_uri                 (GstQuery *query,
                                                         gchar **uri);
void                gst_query_set_uri                   (GstQuery *query,
                                                         const gchar *uri);
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_*() functions. Query values can be set using gst_query_set_*(), and parsed using gst_query_parse_*() helpers.
The following example shows how to query the duration of a pipeline:
Example 16. Query duration on a pipeline
| 1 2 3 4 5 6 7 8 9 10 11 12 13 | 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)
typedef struct {
  GstMiniObject mini_object;
  GstQueryType type;
  GstStructure *structure;
} GstQuery;
The GstQuery structure.
| GstMiniObject  | The parent GstMiniObject type | 
| GstQueryType  | the GstQueryType | 
| GstStructure * | the GstStructure containing the query details. | 
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,
  GST_QUERY_BUFFERING,
  GST_QUERY_CUSTOM,
  GST_QUERY_URI
} GstQueryType;
Standard predefined Query types
| invalid query type | |
| current position in stream | |
| total duration of the stream | |
| latency of stream | |
| current jitter of stream | |
| current rate of the stream | |
| seeking capabilities | |
| segment start/stop positions | |
| convert values between formats | |
| query supported formats for convert | |
| query available media for efficient seeking. Since 0.10.20. | |
| a custom application or element defined query. Since 0.10.22. | |
| query the URI of the source or sink. Since 0.10.22. | 
#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.
| 
 | the query to query | 
Since 0.10.4
typedef struct {
  GstQueryType   value;
  const gchar   *nick;
  const gchar   *description;
  GQuark         quark;
} GstQueryTypeDefinition;
A Query Type definition
| GstQueryType  | the unique id of the Query type | 
| const gchar * | a short nick | 
| const gchar * | a longer description of the query type | 
| GQuark  | the quark for the nick | 
const gchar*        gst_query_type_get_name             (GstQueryType query);
Get a printable name for the given query type. Do not modify or free.
| 
 | the query type | 
| Returns : | a reference to the static name of the query. | 
GQuark              gst_query_type_to_quark             (GstQueryType query);
Get the unique quark for the given query type.
| 
 | the query type | 
| Returns : | the quark associated with the query type | 
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
| 
 | The nick of the new query | 
| 
 | The description of the new query | 
| Returns : | A new GstQueryType or an already registered query with the same nick. | 
GstQueryType        gst_query_type_get_by_nick          (const gchar *nick);
Get the query type registered with nick.
| 
 | The nick of the query | 
| Returns : | The query registered with nickor GST_QUERY_NONE
if the query was not registered. | 
gboolean gst_query_types_contains (const GstQueryType *types,GstQueryType type);
See if the given GstQueryType is inside the types query types array.
| 
 | The query array to search | 
| 
 | the GstQueryType to find | 
| Returns : | TRUE if the type is found inside the array | 
const GstQueryTypeDefinition * gst_query_type_get_details
                                                        (GstQueryType type);
Get details about the given GstQueryType.
| 
 | a GstQueryType | 
| Returns : | The GstQueryTypeDefinition for typeor NULL on failure. | 
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. | 
GstQuery *          gst_query_ref                       (GstQuery *q);
Increases the refcount of the given query by one.
| 
 | a GstQuery to increase the refcount of. | 
| Returns : | q | 
void                gst_query_unref                     (GstQuery *q);
Decreases the refcount of the query. If the refcount reaches 0, the query will be freed.
| 
 | a GstQuery to decrease the refcount of. | 
GstQuery *          gst_query_copy                      (const GstQuery *q);
Copies the given query using the copy function of the parent GstStructure.
| 
 | a GstQuery to copy. | 
| Returns : | a new copy of q. | 
#define gst_query_make_writable(q) GST_QUERY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (q)))
Makes a writable query from the given query.
| 
 | a GstQuery to make writable | 
GstQuery * gst_query_new_application (GstQueryType type,GstStructure *structure);
Constructs a new custom application query object. Use gst_query_unref()
when done with it.
| 
 | the query type | 
| 
 | a structure for the query | 
| Returns : | a GstQuery | 
GstStructure *      gst_query_get_structure             (GstQuery *query);
Get the structure of a 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. | 
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.
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.
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.
| 
 | a GstQuery | 
| 
 | the storage for the GstFormat of the source value, or NULL. [out] | 
| 
 | the storage for the source value, or NULL. [out] | 
| 
 | the storage for the GstFormat of the destination value, or NULL. [out] | 
| 
 | the storage for the destination value, or NULL. [out] | 
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.
void gst_query_set_position (GstQuery *query,GstFormat format,gint64 cur);
Answer a position query by setting the requested value in the given format.
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.
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.
void gst_query_set_duration (GstQuery *query,GstFormat format,gint64 duration);
Answer a duration query by setting the requested value in the given format.
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.
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
void gst_query_parse_latency (GstQuery *query,gboolean *live,GstClockTime *min_latency,GstClockTime *max_latency);
Parse a latency query answer.
| 
 | a GstQuery | 
| 
 | storage for live or NULL. [out] | 
| 
 | the storage for the min latency or NULL. [out] | 
| 
 | the storage for the max latency or NULL. [out] | 
Since 0.10.12
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.
| 
 | a GstQuery | 
| 
 | if there is a live element upstream | 
| 
 | the minimal latency of the live element | 
| 
 | the maximal latency of the live element | 
Since 0.10.12
GstQuery*           gst_query_new_seeking               (GstFormat format);
Constructs a new query object for querying seeking properties of the stream.
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.
| 
 | a GstQuery | 
| 
 | the format to set for the segment_startandsegment_endvalues | 
| 
 | the seekable flag to set | 
| 
 | the segment_start to set | 
| 
 | the segment_end to set | 
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
| 
 | a GST_QUERY_SEEKING type query GstQuery | 
| 
 | the format to set for the segment_startandsegment_endvalues. [out] | 
| 
 | the seekable flag to set. [out] | 
| 
 | the segment_start to set. [out] | 
| 
 | the segment_end to set. [out] | 
GstQuery*           gst_query_new_formats               (void);
Constructs a new query object for querying formats of the stream.
| Returns : | A GstQuery | 
Since 0.10.4
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.
| 
 | a GstQuery | 
| 
 | the number of formats to set. | 
| 
 | A number of GstFormatsequal ton_formats. | 
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.
| 
 | a GstQuery | 
| 
 | the number of formats to set. | 
| 
 | An array containing n_formatsGstFormatvalues. | 
Since 0.10.4
void gst_query_parse_formats_length (GstQuery *query,guint *n_formats);
Parse the number of formats in the formats query.
| 
 | a GstQuery | 
| 
 | the number of formats in this query. [out] | 
Since 0.10.4
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.
| 
 | a GstQuery | 
| 
 | the nth format to retrieve. [out] | 
| 
 | a pointer to store the nth format. [out] | 
Since 0.10.4
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.
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.
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.
typedef enum {
  GST_BUFFERING_STREAM,
  GST_BUFFERING_DOWNLOAD,
  GST_BUFFERING_TIMESHIFT,
  GST_BUFFERING_LIVE
} GstBufferingMode;
The different types of buffering methods.
GstQuery*           gst_query_new_buffering             (GstFormat format);
Constructs a new query object for querying the buffering status of a stream.
Since 0.10.20
void gst_query_set_buffering_percent (GstQuery *query,gboolean busy,gint percent);
Set the percentage of buffered data. This is a value between 0 and 100.
The busy indicator is TRUE when the buffering is in progress.
| 
 | A valid GstQuery of type GST_QUERY_BUFFERING. | 
| 
 | if buffering is busy | 
| 
 | a buffering percent | 
Since 0.10.20
void gst_query_parse_buffering_percent (GstQuery *query,gboolean *busy,gint *percent);
Get the percentage of buffered data. This is a value between 0 and 100.
The busy indicator is TRUE when the buffering is in progress.
| 
 | A valid GstQuery of type GST_QUERY_BUFFERING. | 
| 
 | if buffering is busy. [out] | 
| 
 | a buffering percent. [out] | 
Since 0.10.20
void gst_query_set_buffering_stats (GstQuery *query,GstBufferingMode mode,gint avg_in,gint avg_out,gint64 buffering_left);
Configures the buffering stats values in query.
| 
 | A valid GstQuery of type GST_QUERY_BUFFERING. | 
| 
 | a buffering mode | 
| 
 | the average input rate | 
| 
 | the average output rate | 
| 
 | amount of buffering time left | 
Since 0.10.20
void gst_query_parse_buffering_stats (GstQuery *query,GstBufferingMode *mode,gint *avg_in,gint *avg_out,gint64 *buffering_left);
Extracts the buffering stats values from query.
| 
 | A valid GstQuery of type GST_QUERY_BUFFERING. | 
| 
 | a buffering mode. [out] | 
| 
 | the average input rate. [out] | 
| 
 | the average output rate. [out] | 
| 
 | amount of buffering time left. [out] | 
Since 0.10.20
void gst_query_set_buffering_range (GstQuery *query,GstFormat format,gint64 start,gint64 stop,gint64 estimated_total);
Set the available query result fields in query.
| 
 | a GstQuery | 
| 
 | the format to set for the startandstopvalues | 
| 
 | the start to set | 
| 
 | the stop to set | 
| 
 | estimated total amount of download time | 
Since 0.10.20
void gst_query_parse_buffering_range (GstQuery *query,GstFormat *format,gint64 *start,gint64 *stop,gint64 *estimated_total);
Parse an available query, writing the format into format, and
other results into the passed parameters, if the respective parameters
are non-NULL
| 
 | a GST_QUERY_BUFFERING type query GstQuery | 
| 
 | the format to set for the segment_startandsegment_endvalues. [out] | 
| 
 | the start to set. [out] | 
| 
 | the stop to set. [out] | 
| 
 | estimated total amount of download time. [out] | 
Since 0.10.20
gboolean gst_query_add_buffering_range (GstQuery *query,gint64 start,gint64 stop);
Set the buffering-ranges array field in query. The current last
start position of the array should be inferior to start.
| 
 | a GST_QUERY_BUFFERING type query GstQuery | 
| 
 | start position of the range | 
| 
 | stop position of the range | 
| Returns : | a gboolean indicating if the range was added or not. | 
Since 0.10.31
guint               gst_query_get_n_buffering_ranges    (GstQuery *query);
Retrieve the number of values currently stored in the buffered-ranges array of the query's structure.
Since 0.10.31
gboolean gst_query_parse_nth_buffering_range (GstQuery *query,guint index,gint64 *start,gint64 *stop);
Parse an available query and get the start and stop values stored
at the index of the buffered ranges array.
| 
 | a GST_QUERY_BUFFERING type query GstQuery | 
| 
 | position in the buffered-ranges array to read | 
| 
 | the start position to set. [out] | 
| 
 | the stop position to set. [out] | 
| Returns : | a gboolean indicating if the parsing succeeded. | 
Since 0.10.31
GstQuery *          gst_query_new_uri                   (void);
Constructs a new query URI query object. Use gst_query_unref()
when done with it. An URI query is used to query the current URI
that is used by the source or sink.
| Returns : | A GstQuery | 
Since 0.10.22
void gst_query_parse_uri (GstQuery *query,gchar **uri);
Parse an URI query, writing the URI into uri as a newly
allocated string, if the respective parameters are non-NULL.
Free the string with g_free() after usage.
| 
 | a GstQuery | 
| 
 | the storage for the current URI (may be NULL). [out] | 
Since 0.10.22