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_RATE_DEN
            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);
#define     gst_query_copy                  (q)
GstStructure* gst_query_get_structure       (GstQuery *query);
#define     gst_query_make_writable         (q)
GstQuery*   gst_query_new_application       (GstQueryType type,
                                             GstStructure *structure);
GstQuery*   gst_query_new_convert           (GstFormat src_format,
                                             gint64 value,
                                             GstFormat dest_format);
GstQuery*   gst_query_new_position          (GstFormat format);
GstQuery*   gst_query_new_duration          (GstFormat format);
GstQuery*   gst_query_new_seeking           (GstFormat format);
void        gst_query_parse_convert         (GstQuery *query,
                                             GstFormat *src_format,
                                             gint64 *src_value,
                                             GstFormat *dest_format,
                                             gint64 *dest_value);
void        gst_query_parse_position        (GstQuery *query,
                                             GstFormat *format,
                                             gint64 *cur);
void        gst_query_parse_duration        (GstQuery *query,
                                             GstFormat *format,
                                             gint64 *duration);
void        gst_query_parse_seeking         (GstQuery *query,
                                             GstFormat *format,
                                             gboolean *seekable,
                                             gint64 *segment_start,
                                             gint64 *segment_end);
#define     gst_query_ref                   (q)
void        gst_query_set_convert           (GstQuery *query,
                                             GstFormat src_format,
                                             gint64 src_value,
                                             GstFormat dest_format,
                                             gint64 dest_value);
void        gst_query_set_formats           (GstQuery *query,
                                             gint n_formats,
                                             ...);
void        gst_query_set_position          (GstQuery *query,
                                             GstFormat format,
                                             gint64 cur);
void        gst_query_set_duration          (GstQuery *query,
                                             GstFormat format,
                                             gint64 duration);
void        gst_query_set_seeking           (GstQuery *query,
                                             GstFormat format,
                                             gboolean seekable,
                                             gint64 segment_start,
                                             gint64 segment_end);
GstIterator* gst_query_type_iterate_definitions
                                            (void);
#define     gst_query_unref                 (q)
void        gst_query_set_segment           (GstQuery *query,
                                             gdouble rate,
                                             GstFormat format,
                                             gint64 start_value,
                                             gint64 stop_value);
GstQuery*   gst_query_new_segment           (GstFormat format);
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.

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_RATE_DEN

#define GST_QUERY_TYPE_RATE_DEN          G_GINT64_CONSTANT (1000000)

Rates are relative to this value


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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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.


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_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.

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_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_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.

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