gstreamer/markdown/design/query.md

# Query

## Purpose

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

## Requirements

  - multiple return values, grouped together when they make sense.

  - one pad function to perform the query

  - extensible queries.

## Implementation

  - `GstQuery` extends `GstMiniObject` and contains a `GstStructure` (see
    `GstMessage`)

  - some standard query types are defined below

  - methods to create and parse the results in the `GstQuery`.

  - define pad
        method:

``` c
        gboolean                (*GstPadQueryFunction)          (GstPad    *pad,
                                                                 GstObject *parent,
                                                                 GstQuery  *query);
```

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

## Query types

**`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. (See [latency](design/latency.md))

**`GST_QUERY_RATE`**: get the current playback rate of the pipeline

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

**`GST_QUERY_BUFFERING`**: query available media for efficient seeking (See [buffering](design/buffering.md))

**`GST_QUERY_CUSTOM`**: a custom query, the name of the query defines the properties of the query.

**`GST_QUERY_URI`**: query the uri of the source or sink element

**`GST_QUERY_ALLOCATION`**: the buffer allocation properties (See [bufferpool](design/bufferpool.md))

**`GST_QUERY_SCHEDULING`**: the scheduling properties (See [scheduling](design/scheduling.md))

**`GST_QUERY_ACCEPT_CAPS`**: check if caps are supported (See [negotiation](design/negotiation.md))

**`GST_QUERY_CAPS`**: get the possible caps (See [negotiation](design/negotiation.md))