gstreamer/docs/design/part-query.txt

DRAFT Query
-----------

Purpose

  Queries are used to get information about the stream. 
  A query is started on a specific pad and travels up or downstream.

Types of queries

  - get length of stream
  - get position in stream
  - get seeking capabilities
  - get latency
  - convert one value to another
  - query supported formats
  - query internal links.

Current implementation

  The current implementation of query requires pads to implement the 
  following functions:

     gboolean                (*GstPadConvertFunction)        (GstPad *pad,
                                                              GstFormat src_format,  gint64  src_value,
                                                              GstFormat *dest_format, gint64 *dest_value);
     gboolean                (*GstPadQueryFunction)          (GstPad *pad, GstQueryType type,
                                                              GstFormat *format, gint64  *value);
     GList*                  (*GstPadIntLinkFunction)        (GstPad *pad);
     const GstFormat*        (*GstPadFormatsFunction)        (GstPad *pad);
     const GstEventMask*     (*GstPadEventMaskFunction)      (GstPad *pad);
     const GstQueryType*     (*GstPadQueryTypeFunction)      (GstPad *pad);

  Most of these functions are not very extensible in particular,
  the queryfunction can only return one value.


Requirements

  - multiple return values, grouped together when they make sense.
  - one pad function to perform the query
  - extensible queries.

Proposition

  - define GstQuery extending GstMiniObject and containing a GstStructure (see GstMessage)
  - define standard query types (see proposed types)
  - define methods to create a parse the results in the GstQuery.
  - define pad method:

     gboolean                (*GstPadQueryFunction)          (GstPad *pad, GstQuery *query);

    pad returns result in query structure and TRUE as result or FALSE when
    query is not supported.

Proposed types

 - GST_QUERY_SEEKING:
   
     get info on how seeking can be done 
       - getrange, with/without offset/size
       - ranges where seeking is efficient (for caching network sources)
       - flags describing seeking behaviour (forward, backward, segments,
	             play backwards, ...)

 - GST_QUERY_POSITION:
  
     get info on current position of the stream in stream_time.

 - GST_QUERY_DURATION:

     get info on the total duration of the stream.
 
 - GST_QUERY_LATENCY:

     get amount of latency introduced in the pipeline. 

 - GST_QUERY_SEGMENT:

     get info about the currently configured playback segment.

 - GST_QUERY_CONVERT:

     convert format/value to another format/value pair.

 - GST_QUERY_FORMATS:

     return list of supported formats that can be used for GST_QUERY_CONVERT.