RygelDataSource

## 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

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.

## Details

### enum RygelDataSourceError

    typedef enum {
    	RYGEL_DATA_SOURCE_ERROR_GENERAL,
    	RYGEL_DATA_SOURCE_ERROR_SEEK_FAILED
    } RygelDataSourceError;

### 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.

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.

### 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.

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

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

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