![]() |
![]() |
![]() |
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> struct GstQuery; enum GstQueryType; #define GST_QUERY_TYPE_NAME (query) struct 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
,const 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 new query types to the gstreamer
core and use them.
Queries can be performed on pads (gst_pad_query()
) and elements
(gst_element_query()
). Please note that some queries might need a running
pipeline to work.
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)
struct GstQuery { GstMiniObject mini_object; GstQueryType type; GstStructure *structure; };
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
struct GstQueryTypeDefinition { GstQueryType value; const gchar *nick; const gchar *description; GQuark quark; };
A Query Type definition
GstQueryType |
the unique id of the Query type |
a short nick | |
a longer description of the query type | |
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 nick or 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 type or 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.
Free-function: gst_iterator_free
Returns : |
a GstIterator of GstQueryTypeDefinition. [transfer full] |
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.
Free-function: gst_query_unref
|
a GstQuery to copy. |
Returns : |
a new copy of q . [transfer full]
|
#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. [transfer full] |
Returns : |
a new writable query (possibly same as q ). [transfer full]
|
GstQuery * gst_query_new_application (GstQueryType type
,GstStructure *structure
);
Constructs a new custom application query object. Use gst_query_unref()
when done with it.
Free-function: gst_query_unref
|
the query type |
|
a structure for the query |
Returns : |
a new GstQuery. [transfer full] |
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. [transfer none] |
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.
Free-function: gst_query_unref
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][allow-none] |
|
the storage for the source value, or NULL. [out][allow-none] |
|
the storage for the GstFormat of the destination value, or NULL. [out][allow-none] |
|
the storage for the destination value, or NULL. [out][allow-none] |
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.
Free-function: gst_query_unref
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.
Free-function: gst_query_unref
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.
Free-function: gst_query_unref
Returns : |
a GstQuery. [transfer full] |
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][allow-none] |
|
the storage for the min latency or NULL. [out][allow-none] |
|
the storage for the max latency or NULL. [out][allow-none] |
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.
Free-function: gst_query_unref
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_start and segment_end values |
|
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_start
and segment_end values, or NULL. [out][allow-none]
|
|
the seekable flag to set, or NULL. [out][allow-none] |
|
the segment_start to set, or NULL. [out][allow-none] |
|
the segment_end to set, or NULL. [out][allow-none] |
GstQuery * gst_query_new_formats (void
);
Constructs a new query object for querying formats of the stream.
Free-function: gst_query_unref
Returns : |
a new GstQuery. [transfer full] |
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 GstFormats equal to n_formats . |
void gst_query_set_formatsv (GstQuery *query
,gint n_formats
,const 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_formats
GstFormat values. [in][array length=n_formats]
|
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.
Free-function: gst_query_unref
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.
|
a GstQuery |
|
the storage for the rate of the segment, or NULL. [out][allow-none] |
|
the storage for the GstFormat of the values, or NULL. [out][allow-none] |
|
the storage for the start value, or NULL. [out][allow-none] |
|
the storage for the stop value, or NULL. [out][allow-none] |
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.
Free-function: gst_query_new
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, or NULL. [out][allow-none] |
|
a buffering percent, or NULL. [out][allow-none] |
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, or NULL. [out][allow-none] |
|
the average input rate, or NULL. [out][allow-none] |
|
the average output rat, or NULLe. [out][allow-none] |
|
amount of buffering time left, or NULL. [out][allow-none] |
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 start and stop values |
|
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_start
and segment_end values, or NULL. [out][allow-none]
|
|
the start to set, or NULL. [out][allow-none] |
|
the stop to set, or NULL. [out][allow-none] |
|
estimated total amount of download time, or NULL. [out][allow-none] |
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.
|
a GST_QUERY_BUFFERING type query GstQuery |
Returns : |
the range array size as a guint. |
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, or NULL. [out][allow-none] |
|
the stop position to set, or NULL. [out][allow-none] |
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.
Free-function: gst_query_unref
Returns : |
a new GstQuery. [transfer full] |
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 callee-allocates][allow-none] |
Since 0.10.22