docs/design/part-query.txt

   1 DRAFT Query
   2 -----------
   3
   4 Status
   5
   6   Implemented, move me to design...
   7
   8 Purpose
   9
  10   Queries are used to get information about the stream.
  11   A query is started on a specific pad and travels up or downstream.
  12
  13 Types of queries
  14
  15   - get length of stream
  16   - get position in stream
  17   - get seeking capabilities
  18   - get latency
  19   - convert one value to another
  20   - query supported formats
  21   - query internal links.
  22
  23 Current implementation
  24
  25   The current implementation of query requires pads to implement the
  26   following functions:
  27
  28      gboolean                (*GstPadConvertFunction)        (GstPad *pad,
  29                                                               GstFormat src_format,  gint64  src_value,
  30                                                               GstFormat *dest_format, gint64 *dest_value);
  31      gboolean                (*GstPadQueryFunction)          (GstPad *pad, GstQueryType type,
  32                                                               GstFormat *format, gint64  *value);
  33      GList*                  (*GstPadIntLinkFunction)        (GstPad *pad);
  34      const GstFormat*        (*GstPadFormatsFunction)        (GstPad *pad);
  35      const GstEventMask*     (*GstPadEventMaskFunction)      (GstPad *pad);
  36      const GstQueryType*     (*GstPadQueryTypeFunction)      (GstPad *pad);
  37
  38   Most of these functions are not very extensible in particular,
  39   the queryfunction can only return one value.
  40
  41
  42 Requirements
  43
  44   - multiple return values, grouped together when they make sense.
  45   - one pad function to perform the query
  46   - extensible queries.
  47
  48 Proposition
  49
  50   - define GstQuery extending GstData and containing a GstStructure (see GstMessage)
  51   - define standard query types (see proposed types)
  52   - define methods to create a parse the results in the GstQuery.
  53   - define pad method:
  54
  55      gboolean                (*GstPadQueryFunction)          (GstPad *pad, GstQuery *query);
  56
  57     pad returns result in query structure and TRUE as result or FALSE when
  58     query is not supported.
  59
  60 Proposed types
  61
  62  - GST_QUERY_SEEKING:
  63
  64      - get info on how seeking can be done
  65          - getrange, with/without offset/size
  66          - ranges where seeking is efficient (for caching network sources)
  67          - flags describing seeking behaviour (forward, backward, segments,
  68                      play backwards, ...)
  69
  70  - GST_QUERY_POSITION:
  71
  72      - get info on current position of the stream
  73        - start position
  74        - current position
  75        - end position
  76        - length
  77
  78  - GST_QUERY_LATENCY:
  79
  80      - get amount of buffering
  81
  82  - GST_QUERY_CONVERT:
  83
  84      - convert format/value to another format/value pair.
  85
  86  - GST_QUERY_FORMATS:
  87
  88      - return list of supported formats.
  89
  90 Also????
  91
  92  - GST_QUERY_CAPS:
  93