GrlSourceRemoveCb ()

void
(*GrlSourceRemoveCb) (GrlSource *source,
                      GrlMedia *media,
                      gpointer user_data,
                      const GError *error);

Prototype for the callback passed to grl_source_remove()

GrlSourceResolveCb ()

void
(*GrlSourceResolveCb) (GrlSource *source,
                       guint operation_id,
                       GrlMedia *media,
                       gpointer user_data,
                       const GError *error);

Prototype for the callback passed to grl_source_resolve(). If the URI did not resolve to a valid media record, media will be NULL. If there was an error during resolution, error will be set.

If media is non-NULL, ownership of it is transferred to the callback, and it must be freed afterwards using g_object_unref().

GrlSourceResultCb ()

void
(*GrlSourceResultCb) (GrlSource *source,
                      guint operation_id,
                      GrlMedia *media,
                      guint remaining,
                      gpointer user_data,
                      const GError *error);

Prototype for the callback passed to the media sources' methods

GrlSourceStoreCb ()

void
(*GrlSourceStoreCb) (GrlSource *source,
                     GrlMedia *media,
                     GList *failed_keys,
                     gpointer user_data,
                     const GError *error);

Prototype for the callback passed to grl_source_store_foo functions

grl_source_browse ()

guint
grl_source_browse (GrlSource *source,
                   GrlMedia *container,
                   const GList *keys,
                   GrlOperationOptions *options,
                   GrlSourceResultCb callback,
                   gpointer user_data);

Browse from media elements through an available list.

This method is asynchronous.

Since: 0.2.0

grl_source_browse_sync ()

GList *
grl_source_browse_sync (GrlSource *source,
                        GrlMedia *container,
                        const GList *keys,
                        GrlOperationOptions *options,
                        GError **error);

Browse media elements through an available list.

This method is synchronous.

Since: 0.2.0

grl_source_get_auto_split_threshold ()

guint
grl_source_get_auto_split_threshold (GrlSource *source);

Gets how much elements the source is able to handle in a single request.

See grl_source_set_auto_split_threshold()

Since: 0.2.0

grl_source_get_caps ()

GrlCaps *
grl_source_get_caps (GrlSource *source,
                     GrlSupportedOps operation);

Get the capabilities of source for operation .

Since: 0.2.0

grl_source_get_description ()

const gchar *
grl_source_get_description (GrlSource *source);

Since: 0.2.0

grl_source_get_icon ()

GIcon *
grl_source_get_icon (GrlSource *source);

Since: 0.2.8

grl_source_get_id ()

const gchar *
grl_source_get_id (GrlSource *source);

Since: 0.2.0

grl_source_get_media_from_uri ()

guint
grl_source_get_media_from_uri (GrlSource *source,
                               const gchar *uri,
                               const GList *keys,
                               GrlOperationOptions *options,
                               GrlSourceResolveCb callback,
                               gpointer user_data);

Creates an instance of GrlMedia representing the media resource exposed at uri .

It is recommended to call grl_source_test_media_from_uri() before invoking this to check whether the target source can theoretically do the resolution.

This method is asynchronous.

Since: 0.2.0

grl_source_get_media_from_uri_sync ()

GrlMedia *
grl_source_get_media_from_uri_sync (GrlSource *source,
                                    const gchar *uri,
                                    const GList *keys,
                                    GrlOperationOptions *options,
                                    GError **error);

Creates an instance of GrlMedia representing the media resource exposed at uri .

It is recommended to call grl_source_test_media_from_uri() before invoking this to check whether the target source can theoretically do the resolution.

This method is synchronous.

Since: 0.2.0

grl_source_get_name ()

const gchar *
grl_source_get_name (GrlSource *source);

Since: 0.2.0

grl_source_get_plugin ()

GrlPlugin *
grl_source_get_plugin (GrlSource *source);

Since: 0.2.0

grl_source_get_rank ()

gint
grl_source_get_rank (GrlSource *source);

Gets the source rank

Since: 0.2.0

grl_source_get_supported_media ()

GrlSupportedMedia
grl_source_get_supported_media (GrlSource *source);

Gets the supported type of medias source can deal with.

Since: 0.3.0

grl_source_get_tags ()

const char **
grl_source_get_tags (GrlSource *source);

Since: 0.2.10

grl_source_may_resolve ()

gboolean
grl_source_may_resolve (GrlSource *source,
                        GrlMedia *media,
                        GrlKeyID key_id,
                        GList **missing_keys);

Checks whether key_id may be resolved with source for media , so that the caller can avoid calling grl_source_resolve() if it can be known in advance it will fail.

If the resolution is known to be impossible because more keys are needed in media , and missing_keys is not NULL , it is populated with the list of GrlKeyID that would be needed.

This function is synchronous and should not block.

Since: 0.2.0

grl_source_notify_change ()

void
grl_source_notify_change (GrlSource *source,
                          GrlMedia *media,
                          GrlSourceChangeType change_type,
                          gboolean location_unknown);

Emits "content-changed" signal to notify subscribers that a change ocurred in source .

See grl_source_notify_change_list() function.

Since: 0.2.0

grl_source_notify_change_list ()

void
grl_source_notify_change_list (GrlSource *source,
                               GPtrArray *changed_medias,
                               GrlSourceChangeType change_type,
                               gboolean location_unknown);

Emits "content-changed" signal to notify subscribers that a change ocurred in source .

The function will take ownership of changed medias and it should not be manipulated in any way by the caller after invoking this function. If that is needed, the caller must ref the array in advance.

See GrlSource::content-changed signal.

Since: 0.2.0

grl_source_notify_change_start ()

gboolean
grl_source_notify_change_start (GrlSource *source,
                                GError **error);

Starts emitting ::content-changed signals when source discovers changes in the content. This instructs source to setup the machinery needed to be aware of changes in the content.

Since: 0.2.0

grl_source_notify_change_stop ()

gboolean
grl_source_notify_change_stop (GrlSource *source,
                               GError **error);

This will drop emission of ::content-changed signals from source . When this is done source should stop the machinery required for it to track changes in the content.

Since: 0.2.0

grl_source_query ()

guint
grl_source_query (GrlSource *source,
                  const gchar *query,
                  const GList *keys,
                  GrlOperationOptions *options,
                  GrlSourceResultCb callback,
                  gpointer user_data);

Execute a specialized query (specific for each provider) on a media repository.

It is different from grl_source_search() semantically, because the query implies a carefully crafted string, rather than a simple string to search.

This method is asynchronous.

Since: 0.2.0

grl_source_query_sync ()

GList *
grl_source_query_sync (GrlSource *source,
                       const gchar *query,
                       const GList *keys,
                       GrlOperationOptions *options,
                       GError **error);

Execute a specialized query (specific for each provider) on a media repository.

This method is synchronous.

Since: 0.2.0

grl_source_remove ()

void
grl_source_remove (GrlSource *source,
                   GrlMedia *media,
                   GrlSourceRemoveCb callback,
                   gpointer user_data);

Remove a media from the source repository.

This method is asynchronous.

Since: 0.2.0

grl_source_remove_sync ()

void
grl_source_remove_sync (GrlSource *source,
                        GrlMedia *media,
                        GError **error);

Remove a media from the source repository.

This method is synchronous.

Since: 0.2.0

grl_source_resolve ()

guint
grl_source_resolve (GrlSource *source,
                    GrlMedia *media,
                    const GList *keys,
                    GrlOperationOptions *options,
                    GrlSourceResolveCb callback,
                    gpointer user_data);

This method is intended to fetch the requested keys of metadata of a given media to the media source.

This method is asynchronous.

Since: 0.2.0

grl_source_resolve_sync ()

GrlMedia *
grl_source_resolve_sync (GrlSource *source,
                         GrlMedia *media,
                         const GList *keys,
                         GrlOperationOptions *options,
                         GError **error);

This method is intended to fetch the requested keys of metadata of a given media to the media source.

This method is synchronous.

Since: 0.2.0

grl_source_search ()

guint
grl_source_search (GrlSource *source,
                   const gchar *text,
                   const GList *keys,
                   GrlOperationOptions *options,
                   GrlSourceResultCb callback,
                   gpointer user_data);

Search for the text string in a source for data identified with that string.

If text is NULL then no text filter will be applied, and thus, no media items from source will be filtered. If source does not support NULL-text search operations it should notiy the client by setting GRL_CORE_ERROR_SEARCH_NULL_UNSUPPORTED in callback 's error parameter.

This method is asynchronous.

Since: 0.2.0

grl_source_search_sync ()

GList *
grl_source_search_sync (GrlSource *source,
                        const gchar *text,
                        const GList *keys,
                        GrlOperationOptions *options,
                        GError **error);

Search for the text string in a source for data identified with that string.

If text is NULL then no text filter will be applied, and thus, no media items from source will be filtered. If source does not support NULL-text search operations it should notiy the client by setting GRL_CORE_ERROR_SEARCH_NULL_UNSUPPORTED in the error parameter.

This method is synchronous.

Since: 0.2.0

grl_source_set_auto_split_threshold ()

void
grl_source_set_auto_split_threshold (GrlSource *source,
                                     guint threshold);

Sets how much elements the source is able to handle in a single request.

If user, during a search or browsing operation, asks for more elements than the threshold, the request will be automatically splitted in chunks, so up to threshold elements will be asked in each request.

Source will act as if user were asking just a chunk, and user won't notice that the request was chunked.

Since: 0.2.0

grl_source_slow_keys ()

const GList *
grl_source_slow_keys (GrlSource *source);

Similar to grl_source_supported_keys(), but these keys are marked as slow because of the amount of traffic/processing needed to fetch them.

Since: 0.2.0

grl_source_store ()

void
grl_source_store (GrlSource *source,
                  GrlMedia *parent,
                  GrlMedia *media,
                  GrlWriteFlags flags,
                  GrlSourceStoreCb callback,
                  gpointer user_data);

Store the media into the parent container

This method is asynchronous.

Since: 0.3.0

grl_source_store_metadata ()

void
grl_source_store_metadata (GrlSource *source,
                           GrlMedia *media,
                           GList *keys,
                           GrlWriteFlags flags,
                           GrlSourceStoreCb callback,
                           gpointer user_data);

Get the values for keys from media and store it permanently. After calling this method, future queries that return this media object shall return this new values for the selected keys.

This function is asynchronous and uses the Glib's main loop.

Since: 0.2.0

grl_source_store_metadata_sync ()

GList *
grl_source_store_metadata_sync (GrlSource *source,
                                GrlMedia *media,
                                GList *keys,
                                GrlWriteFlags flags,
                                GError **error);

Update keys values from media in the source . After calling this method, future queries that return this media object shall return this new value for the selected key.

This function is synchronous.

Since: 0.2.0

grl_source_store_sync ()

void
grl_source_store_sync (GrlSource *source,
                       GrlMedia *parent,
                       GrlMedia *media,
                       GrlWriteFlags flags,
                       GError **error);

Store the media into the parent container.

This method is synchronous.

Since: 0.3.0

grl_source_supported_keys ()

const GList *
grl_source_supported_keys (GrlSource *source);

Get a list of GrlKeyID, which describe a metadata types that this source can fetch and store.

Since: 0.2.0

grl_source_supported_operations ()

GrlSupportedOps
grl_source_supported_operations (GrlSource *source);

By default the derived objects of GrlSource can only resolve.

Since: 0.2.0

grl_source_test_media_from_uri ()

gboolean
grl_source_test_media_from_uri (GrlSource *source,
                                const gchar *uri);

Tests whether source can instantiate a GrlMedia object representing the media resource exposed at uri .

Since: 0.2.0

grl_source_writable_keys ()

const GList *
grl_source_writable_keys (GrlSource *source);

Similar to grl_source_supported_keys(), but these keys are marked as writable, meaning the source allows the client to provide new values for these keys that will be stored permanently.

Since: 0.2.0

struct GrlSource

struct GrlSource;

struct GrlSourceClass

struct GrlSourceClass {
  GObjectClass parent_class;

  GrlSupportedOps (*supported_operations) (GrlSource *source);

  const GList * (*supported_keys) (GrlSource *source);

  const GList * (*slow_keys) (GrlSource *source);

  const GList * (*writable_keys) (GrlSource *source);

  GrlCaps * (*get_caps) (GrlSource *source, GrlSupportedOps operation);

  void (*resolve) (GrlSource *source, GrlSourceResolveSpec *ms);

  gboolean (*may_resolve) (GrlSource *source, GrlMedia *media,
                           GrlKeyID key_id, GList **missing_keys);

  gboolean (*test_media_from_uri) (GrlSource *source,
                                   const gchar *uri);

  void (*media_from_uri) (GrlSource *source,
                          GrlSourceMediaFromUriSpec *mfus);

  void (*browse) (GrlSource *source, GrlSourceBrowseSpec *bs);

  void (*search) (GrlSource *source, GrlSourceSearchSpec *ss);

  void (*query) (GrlSource *source, GrlSourceQuerySpec *qs);

  void (*remove) (GrlSource *source, GrlSourceRemoveSpec *rs);

  void (*store) (GrlSource *source, GrlSourceStoreSpec *ss);

  void (*store_metadata) (GrlSource *source, GrlSourceStoreMetadataSpec *sms);

  void (*cancel) (GrlSource *source, guint operation_id);

  gboolean (*notify_change_start) (GrlSource *source,
                                    GError **error);

  gboolean (*notify_change_stop) (GrlSource *source,
                                  GError **error);
};

Grilo Source class. Override the vmethods to implement the element functionality.

enum GrlResolutionFlags

Resolution flags

GrlSourceBrowseSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  GrlMedia *container;
  GList *keys;
  GrlOperationOptions *options;
    GrlSourceResultCb callback;
  gpointer user_data;
} GrlSourceBrowseSpec;

Data transport structure used internally by the plugins which support browse vmethod.

enum GrlSourceChangeType

Specifies which kind of change has happened in the plugin

GrlSourceMediaFromUriSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *uri;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResolveCb callback;
  gpointer user_data;
} GrlSourceMediaFromUriSpec;

Data transport structure used internally by the plugins which support media_from_uri vmethod.

GrlSourceQuerySpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *query;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResultCb callback;
  gpointer user_data;
} GrlSourceQuerySpec;

Data transport structure used internally by the plugins which support query vmethod.

GrlSourceRemoveSpec

typedef struct {
  GrlSource *source;
  gchar *media_id;
  GrlMedia *media;
  GrlSourceRemoveCb callback;
  gpointer user_data;
} GrlSourceRemoveSpec;

Data transport structure used internally by the plugins which support store vmethod.

GrlSourceResolveSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  GrlMedia *media;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResolveCb callback;
  gpointer user_data;
} GrlSourceResolveSpec;

Data transport structure used internally by the plugins which support resolve vmethod.

GrlSourceSearchSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *text;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResultCb callback;
  gpointer user_data;
} GrlSourceSearchSpec;

Data transport structure used internally by the plugins which support search vmethod.

GrlSourceStoreMetadataSpec

typedef struct {
  GrlSource *source;
  GrlMedia *media;
  GList *keys;
  GrlWriteFlags flags;
  GrlSourceStoreCb callback;
  gpointer user_data;
  GList *failed_keys;
} GrlSourceStoreMetadataSpec;

Data transport structure used internally by the plugins which support store_metadata vmethod.

GrlSourceStoreSpec

typedef struct {
  GrlSource *source;
  GrlMedia *parent;
  GrlMedia *media;
  GrlSourceStoreCb callback;
  gpointer user_data;
} GrlSourceStoreSpec;

Data transport structure used internally by the plugins which support store vmethod.

enum GrlSupportedOps

Bitwise flags which reflect the kind of operations that a GrlSource supports.

enum GrlWriteFlags

Flags for writing operations.

The “auto-split-threshold” property

  “auto-split-threshold”     guint

Transparently split queries with count requests bigger than a certain threshold into smaller queries.

Flags: Read / Write

Default value: 0

Since: 0.2.0

The “plugin” property

  “plugin”                   GrlPlugin *

Plugin the source belongs to

Flags: Read / Write / Construct

Since: 0.2.0

The “rank” property

  “rank”                     gint

Source rank

Flags: Read / Write / Construct

Default value: 0

Since: 0.2.0

The “source-desc” property

  “source-desc”              gchar *

A description of the source

Flags: Read / Write / Construct

Default value: ""

Since: 0.2.0

The “source-icon” property

  “source-icon”              GIcon *

GIcon representing the source

Flags: Read / Write / Construct

Since: 0.2.8

The “source-id” property

  “source-id”                gchar *

The identifier of the source.

Flags: Read / Write / Construct

Default value: ""

Since: 0.2.0

The “source-name” property

  “source-name”              gchar *

The name of the source.

Flags: Read / Write / Construct

Default value: ""

Since: 0.2.0

The “source-tags” property

  “source-tags”              GStrv

A string array of tags relevant this source.

The tags are arbitrary, and applications should just pass over the tags it does not understand. Applications would usually use this to either group sources together, or hide certain sources: a radio application would filter for GRL_MEDIA_TYPE_AUDIO in GrlSource::supported-media as well as "radio" being listed in the tags.

To avoid irrelevant content being listed in applications, sources such as generic video sites should not be tagged as "cinema" or "tv" as they contain a lot of content that's not either of those.

This is a list of commonly used values:

Flags: Read / Write / Construct

Since: 0.2.10

The “supported-media” property

  “supported-media”          GrlSupportedMedia

List of supported media types by this source.

Flags: Read / Write / Construct

Default value: GRL_SUPPORTED_MEDIA_AUDIO | GRL_SUPPORTED_MEDIA_VIDEO | GRL_SUPPORTED_MEDIA_IMAGE

Since: 0.2.3

The “content-changed” signal

void
user_function (GrlSource          *source,
               GPtrArray          *changed_medias,
               GrlSourceChangeType change_type,
               gboolean            location_unknown,
               gpointer            user_data)

Signals that the content in the source has changed. changed_medias is the list of elements that have changed. Usually these medias are of type GrlMedia container, meaning that the content of that container has changed.

If location_unknown is TRUE it means the source cannot establish where the change happened: could be either in the container, in any child, or in any other descendant of the container in the hierarchy.

Both change_type and location_unknown are applied to all elements in the list.

For the cases where the source can only signal that a change happened, but not where, it would use a list with the the root container (NULL id) and set location_unknown as TRUE .

Flags: Action

Since: 0.2.0