RygelMediaEngine: librygel-server Reference Manual

## RygelMediaEngine RygelMediaEngine — This is the base class for media engines that contain knowledge about the streaming and transformational capabilites of the media library in use. |

## Functions

GList * | rygel_media_engine_get_dlna_profiles ()
void | rygel_media_engine_get_resources_for_item ()
GeeList * | rygel_media_engine_get_resources_for_item_finish ()
RygelDataSource * | rygel_media_engine_create_data_source_for_resource ()
RygelDataSource * | rygel_media_engine_create_data_source_for_uri ()
GList * | rygel_media_engine_get_internal_protocol_schemes ()
void | rygel_media_engine_init ()
RygelMediaEngine * | rygel_media_engine_get_default ()

## Signals

void | resource-changed | Run Last

## Types and Values

#define | RYGEL_TYPE_MEDIA_ENGINE
struct | RygelMediaEngine
struct | RygelMediaEngineClass
enum | RygelMediaEngineError

## Object Hierarchy

        GObject
        ╰── RygelMediaEngine

## Description

Media engines express what representations of a MediaObject they can produce by returning MediaResource objects which will, in turn, be used to express to endpoints representations can be streamed from the MediaServer. These representations may include transformations, time-scaled representations, and/or encrypted representations.

See, for instance, Rygel's built-in "gstreamer" and "simple" media engines, or the external rygel-gst-0-10-media-engine module.

The actual media engine used by Rygel at runtime is specified by the media-engine configuration key. For instance, in rygel.conf: media-engine=librygel-media-engine-gst.so

Media engines should also derive their own RygelDataSource, returning an instance of it from `create_data_source()`.

See the <link linkend="implementing-media-engines">Implementing Media Engines</link> section.

## Functions

### rygel_media_engine_get_dlna_profiles ()

    GList *
    rygel_media_engine_get_dlna_profiles (RygelMediaEngine *self);

Get a list of the DLNA profiles that the media engine can stream.

This information is needed to implement DLNA's ConnectionManager.GetProtocolInfo call and to determine whether Rygel can accept an uploaded file.

#### Parameters

self | the RygelMediaEngine instance |

#### Returns

A list of RygelDLNAProfile<!-- -->s

.

[transfer none]

### rygel_media_engine_get_resources_for_item ()

    void
    rygel_media_engine_get_resources_for_item
                                   (RygelMediaEngine *self,
                                    RygelMediaObject *item,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Retrieve engine-provided resources for the given MediaObject

The MediaResources returned may include formats/profiles that do not match the source content byte-for-byte (e.g. transcodes, encrypted formats, etc). The MediaEngine must return a MediaResource for the raw MediaObject content if it can support streaming the content directly.

The order of MediaResources in the returned List should be from most-preferred to least-preferred and each must have a unique alphanumeric "name" field.

The engine should set all delivery-related flags assuming all delivery forms are supported (e.g. the protocol fields and delivery flags of the ProtocolInfo). And the resource uri should be set to the empty string for http-delivered resources. The effective delivery options and uri will be established by the HTTP server.

See also: `rygel_media_engine_get_resources_for_item_finish()`

#### Parameters

self | the RygelMediaEngine instance |
item |  |
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to `_callback_` function. | [closure]

### rygel_media_engine_get_resources_for_item_finish ()

    GeeList *
    rygel_media_engine_get_resources_for_item_finish
                                   (RygelMediaEngine *self,
                                    GAsyncResult *_res_);

Retrieve engine-provided resources for the given MediaObject

The MediaResources returned may include formats/profiles that do not match the source content byte-for-byte (e.g. transcodes, encrypted formats, etc). The MediaEngine must return a MediaResource for the raw MediaObject content if it can support streaming the content directly.

The order of MediaResources in the returned List should be from most-preferred to least-preferred and each must have a unique alphanumeric "name" field.

The engine should set all delivery-related flags assuming all delivery forms are supported (e.g. the protocol fields and delivery flags of the ProtocolInfo). And the resource uri should be set to the empty string for http-delivered resources. The effective delivery options and uri will be established by the HTTP server.

See also: `rygel_media_engine_get_resources_for_item()`

#### Parameters

self | the RygelMediaEngine instance |
_res_ | a GAsyncResult |

#### Returns

A list of MediaResources<!-- -->s or null if no representations are provided by the engine for the item.

### rygel_media_engine_create_data_source_for_resource ()

    RygelDataSource *
    rygel_media_engine_create_data_source_for_resource
                                   (RygelMediaEngine *self,
                                    RygelMediaObject *item,
                                    RygelMediaResource *resource,
                                    GHashTable *replacements,
                                    GError **error);

Get a DataSource for given MediaResource representation of the MediaObject.

#### Parameters

self | the RygelMediaEngine instance |
item | . The MediaObject to create the DataSource for . | [in]
resource | . The specific resource to create the DataSource for . | [in]
replacements |  |
error | location to store the error occuring, or `NULL` to ignore |

#### Returns

A DataSource representing the given item resource

### rygel_media_engine_create_data_source_for_uri ()

    RygelDataSource *
    rygel_media_engine_create_data_source_for_uri
                                   (RygelMediaEngine *self,
                                    const gchar *uri,
                                    GError **error);

Get a DataSource for the URI.

#### Parameters

self | the RygelMediaEngine instance |
uri | . to create the DataSource for. . | [in]
error | location to store the error occuring, or `NULL` to ignore |

#### Returns

A DataSource representing the uri

### rygel_media_engine_get_internal_protocol_schemes ()

    GList *
    rygel_media_engine_get_internal_protocol_schemes
                                   (RygelMediaEngine *self);

Get a list of URI schemes that are internal to the engine.

#### Parameters

self | the RygelMediaEngine instance |

#### Returns

A list of strings considered protocol schemees

### rygel_media_engine_init ()

    void
    rygel_media_engine_init (GError **error);

#### Parameters

error | location to store the error occuring, or `NULL` to ignore |

### rygel_media_engine_get_default ()

    RygelMediaEngine *
    rygel_media_engine_get_default (void);

Get the singleton instance of the currently used media engine.

#### Returns

An instance of a concrete RygelMediaEngine implementation.

## Types and Values

### RYGEL_TYPE_MEDIA_ENGINE

    #define RYGEL_TYPE_MEDIA_ENGINE (rygel_media_engine_get_type ())

The type for RygelMediaEngine.

### struct RygelMediaEngine

    struct RygelMediaEngine;

This is the base class for media engines that contain knowledge about the streaming and transformational capabilites of the media library in use.

Media engines express what representations of a MediaObject they can produce by returning MediaResource objects which will, in turn, be used to express to endpoints representations can be streamed from the MediaServer. These representations may include transformations, time-scaled representations, and/or encrypted representations.

See, for instance, Rygel's built-in "gstreamer" and "simple" media engines, or the external rygel-gst-0-10-media-engine module.

The actual media engine used by Rygel at runtime is specified by the media-engine configuration key. For instance, in rygel.conf: media-engine=librygel-media-engine-gst.so

Media engines should also derive their own RygelDataSource, returning an instance of it from `create_data_source()`.

See the <link linkend="implementing-media-engines">Implementing Media Engines</link> section.

### struct RygelMediaEngineClass

    struct RygelMediaEngineClass {
    	GObjectClass parent_class;
    	GList* (*get_dlna_profiles) (RygelMediaEngine* self);
    	void (*get_resources_for_item) (RygelMediaEngine* self, RygelMediaObject* item, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	GeeList* (*get_resources_for_item_finish) (RygelMediaEngine* self, GAsyncResult* _res_);
    	RygelDataSource* (*create_data_source_for_resource) (RygelMediaEngine* self, RygelMediaObject* item, RygelMediaResource* resource, GHashTable* replacements, GError** error);
    	RygelDataSource* (*create_data_source_for_uri) (RygelMediaEngine* self, const gchar* uri, GError** error);
    	GList* (*get_internal_protocol_schemes) (RygelMediaEngine* self);
    };

The class structure for `RYGEL_TYPE_MEDIA_ENGINE`. All the fields in this structure are private and should never be accessed directly.

#### Members

`get_dlna_profiles` () | virtual method called by `rygel_media_engine_get_dlna_profiles()` |
`get_resources_for_item` () | virtual method called by `rygel_media_engine_get_resources_for_item()` |
`get_resources_for_item_finish` () | asynchronous finish function for `get_resources_for_item`, called by `rygel_media_engine_get_resources_for_item()` |
`create_data_source_for_resource` () | virtual method called by `rygel_media_engine_create_data_source_for_resource()` |
`create_data_source_for_uri` () | virtual method called by `rygel_media_engine_create_data_source_for_uri()` |
`get_internal_protocol_schemes` () | virtual method called by `rygel_media_engine_get_internal_protocol_schemes()` |

### enum RygelMediaEngineError

#### Members

RYGEL_MEDIA_ENGINE_ERROR_NOT_FOUND |  |

## Signal Details

### The `“resource-changed”` signal

    void
    user_function (RygelMediaEngine *media_engine,
                   gchar            *media_object_uri,
                   gpointer          user_data)

Signaled when one or more MediaResources<!-- -->s associated with a MediaObject changes. get_resources_for_item should be called in response to this signal to retrieve the updated list of MediaResources for the associated MediaObject.

#### Parameters

media_engine | the RygelMediaEngine instance that received the signal |
media_object_uri | . is the uri associated with a MediaObject.= |
user_data | user data set when the signal handler was connected. |

Flags: Run Last