## RygelDataSource RygelDataSource — Interface for all data streams provided by a RygelMediaEngine. |

## Synopsis

    enum                RygelDataSourceError;
    void                rygel_data_source_start             (RygelDataSource *self,
                                                             RygelHTTPSeek *offsets,
                                                             GError **error);
    void                rygel_data_source_freeze            (RygelDataSource *self);
    void                rygel_data_source_thaw              (RygelDataSource *self);
    void                rygel_data_source_stop              (RygelDataSource *self);
                        RygelDataSource;
    struct              RygelDataSourceIface;

## Object Hierarchy

      GInterface
       +----RygelDataSource

## Prerequisites

RygelDataSource requires GObject.

## Signals

      "data-available"                                 : Run Last
      "done"                                           : Run Last
      "error"                                          : Run Last

## Description

When Rygel receives a HTTP request to stream a given file, it creates a RygelDataSource object for this new file and instructs the RygelDataSource to begin streaming. The RygelDataSource object will duly pass this request on to the underlying media framework, which will in turn pass streamed bytes back to the RygelDataSource object. The RygelDataSource passes these bytes to Rygel which adds them to the response it sends to the original HTTP request received from the client.

The data source is responsible for providing the streamable byte-stream via its data_available signal. End-of-stream is signalled by the done signal, while errors are signalled by the error signal.

Implementations should fulfil at least these requirements:

1. It should support at least the file:// URI scheme.

2. It should be able to stream any kind of binary data, regardless of the format.

RygelDataSource instances are provided by `rygel_media_engine_create_data_source()` which will return a derived RygelDataSource that uses a specific IO backend and/or multimedia backend to stream the multimedia data at the URI.

The derived RygelDataSource may provide additional API for use by the derived media engine. For instance, `rygel_media_engine_get_transcoders()` may return derived RygelTranscoder instances, and these may use that additional API in their `create_source()` implementations, for instance to access resources or data structures of the specific multimedia backend.

## Details

### enum RygelDataSourceError

    typedef enum {
    	RYGEL_DATA_SOURCE_ERROR_GENERAL,
    	RYGEL_DATA_SOURCE_ERROR_SEEK_FAILED
    } RygelDataSourceError;

`RYGEL_DATA_SOURCE_ERROR_GENERAL` |
`RYGEL_DATA_SOURCE_ERROR_SEEK_FAILED` |

### rygel_data_source_start ()

    void                rygel_data_source_start             (RygelDataSource *self,
                                                             RygelHTTPSeek *offsets,
                                                             GError **error);

Start producing the data.

GError will be returned in `error` if anything goes wrong while starting the stream. Throws DataSourceError.SEEK_FAILED if a seek method is not supported or the range is not fulfillable.

`self` : | the RygelDataSource instance
`offsets` : | optional limits of the stream for partial streaming. [in][allow-none]
`error` : | location to store the error occuring, or `NULL` to ignore

### rygel_data_source_freeze ()

    void                rygel_data_source_freeze            (RygelDataSource *self);

Temporarily stop data generation.

May be called multiple times. If the source is already frozen, the following calles to freeze are ignored. After callging `freeze()`, so `data_available()` signal should be emitted.

`self` : | the RygelDataSource instance

### rygel_data_source_thaw ()

    void                rygel_data_source_thaw              (RygelDataSource *self);

Resume data generation from a previous freeze call.

May be called multiple times, will be ignored if the source is not frozen.

`self` : | the RygelDataSource instance

### rygel_data_source_stop ()

    void                rygel_data_source_stop              (RygelDataSource *self);

Stop producing data. After calling `stop()`, calling `start()` should produce data from the beginning and not resume streaming.

`self` : | the RygelDataSource instance

### RygelDataSource

    typedef struct _RygelDataSource RygelDataSource;

Interface for all data streams provided by a RygelMediaEngine.

When Rygel receives a HTTP request to stream a given file, it creates a RygelDataSource object for this new file and instructs the RygelDataSource to begin streaming. The RygelDataSource object will duly pass this request on to the underlying media framework, which will in turn pass streamed bytes back to the RygelDataSource object. The RygelDataSource passes these bytes to Rygel which adds them to the response it sends to the original HTTP request received from the client.

The data source is responsible for providing the streamable byte-stream via its data_available signal. End-of-stream is signalled by the done signal, while errors are signalled by the error signal.

Implementations should fulfil at least these requirements:

1. It should support at least the file:// URI scheme.

2. It should be able to stream any kind of binary data, regardless of the format.

RygelDataSource instances are provided by `rygel_media_engine_create_data_source()` which will return a derived RygelDataSource that uses a specific IO backend and/or multimedia backend to stream the multimedia data at the URI.

The derived RygelDataSource may provide additional API for use by the derived media engine. For instance, `rygel_media_engine_get_transcoders()` may return derived RygelTranscoder instances, and these may use that additional API in their `create_source()` implementations, for instance to access resources or data structures of the specific multimedia backend.

### struct RygelDataSourceIface

    struct RygelDataSourceIface {
    	GTypeInterface parent_iface;
    	void (*start) (RygelDataSource* self, RygelHTTPSeek* offsets, GError** error);
    	void (*freeze) (RygelDataSource* self);
    	void (*thaw) (RygelDataSource* self);
    	void (*stop) (RygelDataSource* self);
    };

Interface for creating RygelDataSource implementations.

GTypeInterface `parent_iface`; | the parent interface structure
`start` () | virtual method called by ``rygel_data_source_start()``
`freeze` () | virtual method called by ``rygel_data_source_freeze()``
`thaw` () | virtual method called by ``rygel_data_source_thaw()``
`stop` () | virtual method called by ``rygel_data_source_stop()``

## Signal Details

### The `"data-available"` signal

    void                user_function                      (RygelDataSource *data_source,
                                                            gpointer         data_length1,
                                                            gint             data,
                                                            gpointer         user_data)         : Run Last

Emitted when the source has produced some data.

This signal has to be emitted in the main thread.

`data_source` : | the RygelDataSource instance that received the signal
`data_length1` : | length of the `data` array
`user_data` : | user data set when the signal handler was connected.

### The `"done"` signal

    void                user_function                      (RygelDataSource *data_source,
                                                            gpointer         user_data)        : Run Last

Emitted when the source does not have data anymore.

This signal has to be emitted in the main thread.

`data_source` : | the RygelDataSource instance that received the signal
`user_data` : | user data set when the signal handler was connected.

### The `"error"` signal

    void                user_function                      (RygelDataSource *data_source,
                                                            gpointer         error,
                                                            gpointer         user_data)        : Run Last

Emitted when the source encounters a problem during data generation.

This signal has to be emitted in the main thread.

`data_source` : | the RygelDataSource instance that received the signal
`user_data` : | user data set when the signal handler was connected.