GrlMetadataSource

GrlMetadataSource — Abstract base class for metadata providers

Synopsis

#include <grilo.h>

enum                GrlMetadataResolutionFlags;
enum                GrlMetadataWritingFlags;
struct              GrlMetadataSource;
void                (*GrlMetadataSourceResolveCb)       (GrlMetadataSource *source,
                                                         GrlMedia *media,
                                                         gpointer user_data,
                                                         const GError *error);
void                (*GrlMetadataSourceSetMetadataCb)   (GrlMetadataSource *source,
                                                         GrlMedia *media,
                                                         GList *failed_keys,
                                                         gpointer user_data,
                                                         const GError *error);
                    GrlMetadataSourceResolveSpec;
                    GrlMetadataSourceSetMetadataSpec;
enum                GrlSupportedOps;
struct              GrlMetadataSourceClass;
GrlSupportedOps     grl_metadata_source_supported_operations
                                                        (GrlMetadataSource *source);
const GList *       grl_metadata_source_supported_keys  (GrlMetadataSource *source);
const GList *       grl_metadata_source_slow_keys       (GrlMetadataSource *source);
GList *             grl_metadata_source_filter_supported
                                                        (GrlMetadataSource *source,
                                                         GList **keys,
                                                         gboolean return_filtered);
GList *             grl_metadata_source_filter_slow     (GrlMetadataSource *source,
                                                         GList **keys,
                                                         gboolean return_filtered);
GList *             grl_metadata_source_filter_writable (GrlMetadataSource *source,
                                                         GList **keys,
                                                         gboolean return_filtered);
const GList *       grl_metadata_source_key_depends     (GrlMetadataSource *source,
                                                         GrlKeyID key_id);
const GList *       grl_metadata_source_writable_keys   (GrlMetadataSource *source);
void                grl_metadata_source_resolve         (GrlMetadataSource *source,
                                                         const GList *keys,
                                                         GrlMedia *media,
                                                         GrlMetadataResolutionFlags flags,
                                                         GrlMetadataSourceResolveCb callback,
                                                         gpointer user_data);
GrlMedia *          grl_metadata_source_resolve_sync    (GrlMetadataSource *source,
                                                         const GList *keys,
                                                         GrlMedia *media,
                                                         GrlMetadataResolutionFlags flags,
                                                         GError **error);
void                grl_metadata_source_set_metadata    (GrlMetadataSource *source,
                                                         GrlMedia *media,
                                                         GList *keys,
                                                         GrlMetadataWritingFlags flags,
                                                         GrlMetadataSourceSetMetadataCb callback,
                                                         gpointer user_data);
GList *             grl_metadata_source_set_metadata_sync
                                                        (GrlMetadataSource *source,
                                                         GrlMedia *media,
                                                         GList *keys,
                                                         GrlMetadataWritingFlags flags,
                                                         GError **error);
const gchar *       grl_metadata_source_get_id          (GrlMetadataSource *source);
const gchar *       grl_metadata_source_get_name        (GrlMetadataSource *source);
const gchar *       grl_metadata_source_get_description (GrlMetadataSource *source);

Object Hierarchy

  GObject
   +----GrlMediaPlugin
         +----GrlMetadataSource
               +----GrlMediaSource

Properties

  "source-desc"              gchar*                : Read / Write / Construct
  "source-id"                gchar*                : Read / Write / Construct
  "source-name"              gchar*                : Read / Write / Construct

Description

GrlMetadataSource is the abstract base class needed to construct a source of metadata that can be used in a Grilo application.

The metadata sources fetch metadata from different online or local databases and store them in the passed GrlMedia.

In opposition to GrlMediaSource, GrlMetadataSource does not create new GrlMedia instances, just fill them up with the metadata provided by the specific GrlMetadataSource.

For example, GrlLastfmAlbumartSource only provides album's covers, and they will be used in the GrlMedia generated by another GrlMediaSource plugin.

The main method is grl_metadata_source_resolve() which will retrieve a list of GrlKeyID requested for the passed GrlMedia.

Details

enum GrlMetadataResolutionFlags

typedef enum {
  GRL_RESOLVE_NORMAL     = 0,        /* Normal mode */
  GRL_RESOLVE_FULL       = (1 << 0), /* Try other plugins if necessary */
  GRL_RESOLVE_IDLE_RELAY = (1 << 1), /* Use idle loop to relay results */
  GRL_RESOLVE_FAST_ONLY  = (1 << 2), /* Only resolve fast metadata keys */
} GrlMetadataResolutionFlags;

GrlMetadata resolution flags

GRL_RESOLVE_NORMAL

Normal mode.

GRL_RESOLVE_FULL

Try other plugins if necessary.

GRL_RESOLVE_IDLE_RELAY

Use idle loop to relay results.

GRL_RESOLVE_FAST_ONLY

Only resolve fast metadata keys.

enum GrlMetadataWritingFlags

typedef enum {
  GRL_WRITE_NORMAL     = 0,        /* Normal mode */
  GRL_WRITE_FULL       = (1 << 0), /* Try other plugins if necessary */
} GrlMetadataWritingFlags;

Flags for metadata writing operations.

GRL_WRITE_NORMAL

Normal mode.

GRL_WRITE_FULL

Try other plugins if necessary.

struct GrlMetadataSource

struct GrlMetadataSource;

GrlMetadataSourceResolveCb ()

void                (*GrlMetadataSourceResolveCb)       (GrlMetadataSource *source,
                                                         GrlMedia *media,
                                                         gpointer user_data,
                                                         const GError *error);

Prototype for the callback passed to grl_metadata_source_resolve()

source :

a metadata source

media :

a GrlMedia transfer object. [transfer full]

user_data :

user data passed to grl_metadata_source_resolve()

error :

possible GError generated when resolving the metadata. [type uint]

GrlMetadataSourceSetMetadataCb ()

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

Prototype for the callback passed to grl_metadata_source_set_metadata()

source :

a metadata source

media :

a GrlMedia transfer object. [transfer full]

failed_keys :

GList of keys that could not be updated, if any. [element-type GObject.ParamSpec][transfer container]

user_data :

user data passed to grl_metadata_source_set_metadata()

error :

possible GError generated when updating the metadata. [type uint]

GrlMetadataSourceResolveSpec

typedef struct {
  GrlMetadataSource *source;
  GList *keys;
  GrlMedia *media;
  GrlMetadataResolutionFlags flags;
  GrlMetadataSourceResolveCb callback;
  gpointer user_data;
} GrlMetadataSourceResolveSpec;

Represents the closure used by the derived objects to fetch, store and return the transfer object to the client's code.

GrlMetadataSource *source;

a metadata source

GList *keys;

the GList of GrlKeyID to fetch and store

GrlMedia *media;

a GrlMedia transfer object

GrlMetadataResolutionFlags flags;

bitwise mask of GrlMetadataResolutionFlags with the resolution strategy

GrlMetadataSourceResolveCb callback;

the callback passed to grl_metadata_source_resolve()

gpointer user_data;

user data passed to grl_metadata_source_resolve()

GrlMetadataSourceSetMetadataSpec

typedef struct {
  GrlMetadataSource *source;
  GrlMedia *media;
  GList *keys;
  GrlMetadataWritingFlags flags;
  GrlMetadataSourceSetMetadataCb callback;
  gpointer user_data;
  GList *failed_keys;
} GrlMetadataSourceSetMetadataSpec;

Represents the closure used by the derived objects to operate.

GrlMetadataSource *source;

a metadata source

GrlMedia *media;

a GrlMedia transfer object

GList *keys;

List of keys to be stored/updated.

GrlMetadataWritingFlags flags;

Flags to control specific bahviors of the set metadata operation.

GrlMetadataSourceSetMetadataCb callback;

the callback passed to grl_metadata_source_set_metadata()

gpointer user_data;

user data passed to grl_metadata_source_set_metadata()

GList *failed_keys;

for internal use of the framework only.

enum GrlSupportedOps

typedef enum {
  GRL_OP_NONE            = 0,
  GRL_OP_METADATA        = 1,
  GRL_OP_RESOLVE         = 1 << 1,
  GRL_OP_BROWSE          = 1 << 2,
  GRL_OP_SEARCH          = 1 << 3,
  GRL_OP_QUERY           = 1 << 4,
  GRL_OP_STORE           = 1 << 5,
  GRL_OP_STORE_PARENT    = 1 << 6,
  GRL_OP_REMOVE          = 1 << 7,
  GRL_OP_SET_METADATA    = 1 << 8,
  GRL_OP_MEDIA_FROM_URI  = 1 << 9,
  GRL_OP_NOTIFY_CHANGE   = 1 << 10,
} GrlSupportedOps;

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

GRL_OP_NONE

no operation is supported

GRL_OP_METADATA

Fetch specific keys of metadata based on the media id.

GRL_OP_RESOLVE

Fetch specific keys of metadata based on other metadata.

GRL_OP_BROWSE

Retrieve complete sets of GrlMedia

GRL_OP_SEARCH

Look up for GrlMedia given a search text

GRL_OP_QUERY

Look up for GrlMedia give a service specific query

GRL_OP_STORE

Store content in a service

GRL_OP_STORE_PARENT

Store content as child of a certian parent category.

GRL_OP_REMOVE

Remove content from a service.

GRL_OP_SET_METADATA

Update metadata of a GrlMedia in a service.

GRL_OP_MEDIA_FROM_URI

Create a GrlMedia instance from an URI representing a media resource.

GRL_OP_NOTIFY_CHANGE

Notify about changes in the GrlMediaSource.

struct GrlMetadataSourceClass

struct GrlMetadataSourceClass {
  GrlMediaPluginClass parent_class;

  GrlSupportedOps (*supported_operations) (GrlMetadataSource *source);

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

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

  const GList * (*key_depends) (GrlMetadataSource *source, GrlKeyID key_id);

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

  void (*resolve) (GrlMetadataSource *source,
		   GrlMetadataSourceResolveSpec *rs);

  void (*set_metadata) (GrlMetadataSource *source,
			GrlMetadataSourceSetMetadataSpec *sms);

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

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

GrlMediaPluginClass parent_class;

the parent class structure

supported_operations ()

the operations that can be called

supported_keys ()

the list of keys that can be handled

slow_keys ()

the list of slow keys that can be fetched

key_depends ()

a deprecated vmethod that will be removed in the future

writable_keys ()

the list of keys which value can be written

resolve ()

resolve the metadata of a given transfer object

set_metadata ()

update metadata values for a given object in a permanent fashion

may_resolve ()

return FALSE if it can be known without blocking that key_id cannot be resolved for media, TRUE otherwise. Optionally fill missing_keys with a list of keys that would be needed to resolve. See grl_metadata_source_may_resolve().

grl_metadata_source_supported_operations ()

GrlSupportedOps     grl_metadata_source_supported_operations
                                                        (GrlMetadataSource *source);

By default the derived objects of GrlMetadataSource can only resolve.

source :

a metadata source

Returns :

a bitwise mangle with the supported operations by the source. [type uint]

Since 0.1.1


grl_metadata_source_supported_keys ()

const GList *       grl_metadata_source_supported_keys  (GrlMetadataSource *source);

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

source :

a metadata source

Returns :

a GList with the keys. [element-type GObject.ParamSpec][transfer none]

Since 0.1.1


grl_metadata_source_slow_keys ()

const GList *       grl_metadata_source_slow_keys       (GrlMetadataSource *source);

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

source :

a metadata source

Returns :

a GList with the keys. [element-type GObject.ParamSpec][transfer none]

Since 0.1.1


grl_metadata_source_filter_supported ()

GList *             grl_metadata_source_filter_supported
                                                        (GrlMetadataSource *source,
                                                         GList **keys,
                                                         gboolean return_filtered);

Compares the received keys list with the supported key list by the metadata source, and deletes those keys which are not supported.

source :

a metadata source

keys :

the list of keys to filter out. [element-type GObject.ParamSpec][transfer container][allow-none][inout]

return_filtered :

if TRUE the return value shall be a new list with the unsupported keys

Returns :

if return_filtered is TRUE will return the list of removed keys; otherwise NULL. [element-type GObject.ParamSpec][transfer container]

Since 0.1.1


grl_metadata_source_filter_slow ()

GList *             grl_metadata_source_filter_slow     (GrlMetadataSource *source,
                                                         GList **keys,
                                                         gboolean return_filtered);

This function does the opposite of other filter functions: removes the slow keys from keys. If return_filtered is TRUE the removed slow keys are returned in a new list.

source :

a metadata source

keys :

the list of keys to filter out. [element-type GObject.ParamSpec][transfer container][allow-none][inout]

return_filtered :

if TRUE the return value shall be a new list with the slow keys

Returns :

if return_filtered is TRUE will return the list of slow keys; otherwise NULL. [element-type GObject.ParamSpec][transfer container]

Since 0.1.1


grl_metadata_source_filter_writable ()

GList *             grl_metadata_source_filter_writable (GrlMetadataSource *source,
                                                         GList **keys,
                                                         gboolean return_filtered);

Similar to grl_metadata_source_filter_supported() but applied to the writable keys in grl_metadata_source_writable_keys().

Filter the keys list keeping only those keys that are writtable in source. If return_filtered is TRUE then the removed keys are returned in a new list.

source :

a metadata source

keys :

the list of keys to filter out. [element-type GObject.ParamSpec][transfer container][allow-none][inout]

return_filtered :

if TRUE the return value shall be a new list with the non-writable keys

Returns :

if return_filtered is TRUE will return the list of non-writtable keys; otherwise NULL. [element-type GObject.ParamSpec][transfer container]

Since 0.1.4


grl_metadata_source_key_depends ()

const GList *       grl_metadata_source_key_depends     (GrlMetadataSource *source,
                                                         GrlKeyID key_id);

Warning

grl_metadata_source_key_depends has been deprecated since version 0.1.10 and should not be used in newly-written code. use grl_metadata_source_may_resolve() instead.

Get the list of GrlKeyID which are needed a priori, in order to fetch and store the requested key_id

source :

a metadata source

key_id :

the requested metadata key. [type GObject.ParamSpec]

Returns :

a GList with the keys, or NULL if it can not resolve key_id. [element-type GObject.ParamSpec][transfer none]

Since 0.1.1


grl_metadata_source_writable_keys ()

const GList *       grl_metadata_source_writable_keys   (GrlMetadataSource *source);

Similar to grl_metadata_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.

source :

a metadata source

Returns :

a GList with the keys. [element-type GObject.ParamSpec][transfer none]

Since 0.1.4


grl_metadata_source_resolve ()

void                grl_metadata_source_resolve         (GrlMetadataSource *source,
                                                         const GList *keys,
                                                         GrlMedia *media,
                                                         GrlMetadataResolutionFlags flags,
                                                         GrlMetadataSourceResolveCb callback,
                                                         gpointer user_data);

This is the main method of the GrlMetadataSource class. It will fetch the metadata of the requested keys.

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

source :

a metadata source

keys :

the GList of GrlKeyID to retrieve. [element-type GObject.ParamSpec][allow-none]

media :

Transfer object where all the metadata is stored.

flags :

bitwise mask of GrlMetadataResolutionFlags with the resolution strategy

callback :

the callback to execute when the media metadata is filled up. [scope notified]

user_data :

user data set for the callback

Since 0.1.4


grl_metadata_source_resolve_sync ()

GrlMedia *          grl_metadata_source_resolve_sync    (GrlMetadataSource *source,
                                                         const GList *keys,
                                                         GrlMedia *media,
                                                         GrlMetadataResolutionFlags flags,
                                                         GError **error);

This is the main method of the GrlMetadataSource class. It will fetch the metadata of the requested keys.

This function is synchronous.

source :

a metadata source

keys :

the GList of GrlKeyID to retrieve. [element-type GObject.ParamSpec][allow-none]

media :

Transfer object where all the metadata is stored

flags :

bitwise mask of GrlMetadataResolutionFlags with the resolution strategy

error :

a GError, or NULL

Returns :

the updated GrlMedia. [transfer full]

Since 0.1.6


grl_metadata_source_set_metadata ()

void                grl_metadata_source_set_metadata    (GrlMetadataSource *source,
                                                         GrlMedia *media,
                                                         GList *keys,
                                                         GrlMetadataWritingFlags flags,
                                                         GrlMetadataSourceSetMetadataCb callback,
                                                         gpointer user_data);

This is the main method of the GrlMetadataSource class. It will 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.

source :

a metadata source

media :

the GrlMedia object that we want to operate on.

keys :

a list of GrlKeyID whose values we want to change. [element-type GObject.ParamSpec][allow-none]

flags :

Flags to configure specific behaviors of the operation.

callback :

the callback to execute when the operation is finished. [scope notified]

user_data :

user data set for the callback

Since 0.1.4


grl_metadata_source_set_metadata_sync ()

GList *             grl_metadata_source_set_metadata_sync
                                                        (GrlMetadataSource *source,
                                                         GrlMedia *media,
                                                         GList *keys,
                                                         GrlMetadataWritingFlags flags,
                                                         GError **error);

This is the main method of the GrlMetadataSource class. It will get the value for key from media and store it permanently. After calling this method, future queries that return this media object shall return this new value for the selected key.

This function is synchronous.

source :

a metadata source

media :

the GrlMedia object that we want to operate on

keys :

a list of GrlKeyID whose values we want to change. [element-type GObject.ParamSpec][allow-none]

flags :

Flags to configure specific behaviors of the operation.

error :

a GError, or NULL

Returns :

a GList of keys that could not be updated, or NULL. [element-type GObject.ParamSpec][transfer container]

Since 0.1.6


grl_metadata_source_get_id ()

const gchar *       grl_metadata_source_get_id          (GrlMetadataSource *source);

source :

a metadata source

Returns :

the ID of the source

Since 0.1.1


grl_metadata_source_get_name ()

const gchar *       grl_metadata_source_get_name        (GrlMetadataSource *source);

source :

a metadata source

Returns :

the name of the source

Since 0.1.1


grl_metadata_source_get_description ()

const gchar *       grl_metadata_source_get_description (GrlMetadataSource *source);

source :

a metadata source

Returns :

the description of the source

Since 0.1.1

Property Details

The "source-desc" property

  "source-desc"              gchar*                : Read / Write / Construct

A description of the source

Default value: ""


The "source-id" property

  "source-id"                gchar*                : Read / Write / Construct

The identifier of the source.

Default value: ""


The "source-name" property

  "source-name"              gchar*                : Read / Write / Construct

The name of the source.

Default value: ""

See Also

GrlMediaPlugin, GrlMediaSource, GrlMedia