docs/design/part-query.txt

   1 Query
   2 -----
   3
   4 Purpose
   5 ~~~~~~~
   6
   7 Queries are used to get information about the stream.
   8 A query is started on a specific pad and travels up or downstream.
   9
  10
  11 Requirements
  12 ~~~~~~~~~~~~
  13
  14   - multiple return values, grouped together when they make sense.
  15   - one pad function to perform the query
  16   - extensible queries.
  17
  18 Implementation
  19 ~~~~~~~~~~~~~~
  20
  21   - GstQuery extends GstMiniObject and contains a GstStructure (see GstMessage)
  22   - some standard query types are defined below
  23   - methods to create and parse the results in the GstQuery.
  24   - define pad method:
  25
  26      gboolean                (*GstPadQueryFunction)          (GstPad    *pad,
  27                                                               GstObject *parent,
  28                                                               GstQuery  *query);
  29
  30     pad returns result in query structure and TRUE as result or FALSE when
  31     query is not supported.
  32
  33 Query types
  34 ~~~~~~~~~~~
  35
  36  - GST_QUERY_POSITION:
  37
  38      get info on current position of the stream in stream_time.
  39
  40  - GST_QUERY_DURATION:
  41
  42      get info on the total duration of the stream.
  43
  44  - GST_QUERY_LATENCY:
  45
  46      get amount of latency introduced in the pipeline. (See part-latency.txt)
  47
  48  - GST_QUERY_RATE:
  49
  50      get the current playback rate of the pipeline
  51
  52  - GST_QUERY_SEEKING:
  53
  54      get info on how seeking can be done
  55        - getrange, with/without offset/size
  56        - ranges where seeking is efficient (for caching network sources)
  57        - flags describing seeking behaviour (forward, backward, segments,
  58                      play backwards, ...)
  59
  60  - GST_QUERY_SEGMENT:
  61
  62      get info about the currently configured playback segment.
  63
  64  - GST_QUERY_CONVERT:
  65
  66      convert format/value to another format/value pair.
  67
  68  - GST_QUERY_FORMATS:
  69
  70      return list of supported formats that can be used for GST_QUERY_CONVERT.
  71
  72  - GST_QUERY_BUFFERING:
  73
  74      query available media for efficient seeking (See part-buffering.txt)
  75
  76  - GST_QUERY_CUSTOM:
  77
  78      a custom query, the name of the query defines the properties of the query.
  79
  80  - GST_QUERY_URI:
  81
  82      query the uri of the source or sink element
  83
  84  - GST_QUERY_ALLOCATION:
  85
  86      the buffer allocation properties (See part-bufferpool.txt)
  87
  88  - GST_QUERY_SCHEDULING:
  89
  90      the scheduling properties (See part-scheduling.txt)
  91
  92  - GST_QUERY_ACCEPT_CAPS:
  93
  94      check if caps are supported (See part-negotiation.txt)
  95
  96  - GST_QUERY_CAPS:
  97
  98      get the possible caps (See part-negotiation.txt)
  99
 100