GrlRegistry

GrlRegistry — Grilo plugins loader and manager

Synopsis

#include <grilo.h>

struct              GrlRegistry;
struct              GrlRegistryClass;
struct              GrlPluginDescriptor;
#define             GRL_PLUGIN_LIST_VAR
#define             GRL_PLUGIN_PATH_VAR
#define             GRL_PLUGIN_RANKS_VAR
#define             GRL_PLUGIN_REGISTER                 (init,
                                                         deinit,
                                                         id)
gboolean            grl_registry_add_config             (GrlRegistry *registry,
                                                         GrlConfig *config,
                                                         GError **error);
gboolean            grl_registry_add_config_from_file   (GrlRegistry *registry,
                                                         const gchar *config_file,
                                                         GError **error);
void                grl_registry_add_directory          (GrlRegistry *registry,
                                                         const gchar *path);
GrlRegistry *       grl_registry_get_default            (void);
GList *             grl_registry_get_metadata_keys      (GrlRegistry *registry);
GList *             grl_registry_get_plugins            (GrlRegistry *registry,
                                                         gboolean only_loaded);
GList *             grl_registry_get_sources            (GrlRegistry *registry,
                                                         gboolean ranked);
GList *             grl_registry_get_sources_by_operations
                                                        (GrlRegistry *registry,
                                                         GrlSupportedOps ops,
                                                         gboolean ranked);
gboolean            grl_registry_load_all_plugins       (GrlRegistry *registry,
                                                         GError **error);
gboolean            grl_registry_load_plugin            (GrlRegistry *registry,
                                                         const gchar *library_filename,
                                                         GError **error);
gboolean            grl_registry_load_plugin_by_id      (GrlRegistry *registry,
                                                         const gchar *plugin_id,
                                                         GError **error);
gboolean            grl_registry_load_plugin_directory  (GrlRegistry *registry,
                                                         const gchar *path,
                                                         GError **error);
GrlKeyID            grl_registry_lookup_metadata_key    (GrlRegistry *registry,
                                                         const gchar *key_name);
const gchar *       grl_registry_lookup_metadata_key_desc
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);
const gchar *       grl_registry_lookup_metadata_key_name
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);
const GList *       grl_registry_lookup_metadata_key_relation
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);
GType               grl_registry_lookup_metadata_key_type
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);
GrlPlugin *         grl_registry_lookup_plugin          (GrlRegistry *registry,
                                                         const gchar *plugin_id);
GrlSource *         grl_registry_lookup_source          (GrlRegistry *registry,
                                                         const gchar *source_id);
gboolean            grl_registry_metadata_key_validate  (GrlRegistry *registry,
                                                         GrlKeyID key,
                                                         GValue *value);
GrlKeyID            grl_registry_register_metadata_key  (GrlRegistry *registry,
                                                         GParamSpec *param_spec,
                                                         GError **error);
void                grl_registry_register_metadata_key_relation
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key1,
                                                         GrlKeyID key2);
gboolean            grl_registry_register_source        (GrlRegistry *registry,
                                                         GrlPlugin *plugin,
                                                         GrlSource *source,
                                                         GError **error);
gboolean            grl_registry_unload_plugin          (GrlRegistry *registry,
                                                         const gchar *plugin_id,
                                                         GError **error);
gboolean            grl_registry_unregister_source      (GrlRegistry *registry,
                                                         GrlSource *source,
                                                         GError **error);

Object Hierarchy

  GObject
   +----GrlRegistry

Signals

  "source-added"                                   : Action
  "source-removed"                                 : Action

Description

The registry holds the metadata of a set of plugins.

The GrlRegistry object is a list of plugins and some functions for dealing with them. Each GrlPlugin is matched 1-1 with a file on disk, and may or may not be loaded a given time. There only can be a single instance of GrlRegistry (singleton pattern).

A GrlPlugin can hold several data GrlSource sources, and GrlRegistry shall register each one of them.

Details

struct GrlRegistry

struct GrlRegistry;

struct GrlRegistryClass

struct GrlRegistryClass {
  GObjectClass parent_class;
};

Grilo Registry class. Dynamic loader of plugins.

GObjectClass parent_class;

the parent class structure

struct GrlPluginDescriptor

struct GrlPluginDescriptor {
  gchar *plugin_id;
  gboolean (*plugin_init) (GrlRegistry *, GrlPlugin *, GList *);
  void (*plugin_deinit) (GrlPlugin *);
  GModule *module;
};

This structure is used for the module loader

gchar *plugin_id;

the module identifier

plugin_init ()

the module initialization. It shall instantiate the GrlPlugins provided

plugin_deinit ()

function to execute when the registry needs to dispose the module.

GModule *module;

the GModule instance.

GRL_PLUGIN_LIST_VAR

#define GRL_PLUGIN_LIST_VAR "GRL_PLUGIN_LIST"

GRL_PLUGIN_PATH_VAR

#define GRL_PLUGIN_PATH_VAR "GRL_PLUGIN_PATH"

GRL_PLUGIN_RANKS_VAR

#define GRL_PLUGIN_RANKS_VAR "GRL_PLUGIN_RANKS"

GRL_PLUGIN_REGISTER()

#define             GRL_PLUGIN_REGISTER(init,                                    \
                                        deinit,                                  \
                                        id)

Define the boilerplate for loadable modules. Defines a new module descriptor which provides a set of GrlPlugins

init :

the module initialization. It shall instantiate the GrlPlugins provided

deinit :

function to execute when the registry needs to dispose the module. [allow-none]

id :

the module identifier

grl_registry_add_config ()

gboolean            grl_registry_add_config             (GrlRegistry *registry,
                                                         GrlConfig *config,
                                                         GError **error);

Add a configuration for a plugin/source.

registry :

the registry instance

config :

a configuration set. [transfer full]

error :

error return location or NULL to ignore

Since 0.2.0


grl_registry_add_config_from_file ()

gboolean            grl_registry_add_config_from_file   (GrlRegistry *registry,
                                                         const gchar *config_file,
                                                         GError **error);

Load plugin configurations from a .ini-like config file.

registry :

the registry instance

config_file :

a key-value file containing the configuration

error :

error return location or NULL to ignore

Returns :

TRUE on success

Since 0.2.0


grl_registry_add_directory ()

void                grl_registry_add_directory          (GrlRegistry *registry,
                                                         const gchar *path);

Set this path as part of default paths to load plugins.

registry :

the registry instance

path :

a path with plugins

Since 0.2.0


grl_registry_get_default ()

GrlRegistry *       grl_registry_get_default            (void);

As the registry is designed to work as a singleton, this method is in charge of creating the only instance or returned it if it is already in memory.

Returns :

a new or an already created instance of the registry. It is NOT MT-safe. [transfer none]

Since 0.2.0


grl_registry_get_metadata_keys ()

GList *             grl_registry_get_metadata_keys      (GrlRegistry *registry);

Returns a list with all registered keys in system.

registry :

the registry instance

Returns :

a GList with all the available GrlKeyIDs. The content of the list should not be modified or freed. Use g_list_free() when done using the list. [transfer container][element-type GrlKeyID]

Since 0.2.0


grl_registry_get_plugins ()

GList *             grl_registry_get_plugins            (GrlRegistry *registry,
                                                         gboolean only_loaded);

This function will return all the available plugins in the registry.

If only_loaded is TRUE, the plugin list will contain only plugins that are loaded.

registry :

the registry instance

only_loaded :

whether the returned list shall include only loaded plugins

Returns :

a GList of available GrlPlugins. The content of the list should not be modified or freed. Use g_list_free() when done using the list. [element-type Grl.Plugin][transfer container]

Since 0.2.0


grl_registry_get_sources ()

GList *             grl_registry_get_sources            (GrlRegistry *registry,
                                                         gboolean ranked);

This function will return all the available sources in the registry.

If ranked is TRUE, the source list will be ordered by rank.

registry :

the registry instance

ranked :

whether the returned list shall be returned ordered by rank

Returns :

a GList of available GrlSources. The content of the list should not be modified or freed. Use g_list_free() when done using the list. [element-type Grl.Source][transfer container]

Since 0.2.0


grl_registry_get_sources_by_operations ()

GList *             grl_registry_get_sources_by_operations
                                                        (GrlRegistry *registry,
                                                         GrlSupportedOps ops,
                                                         gboolean ranked);

Give an array of all the available sources in the registry capable of perform the operations requested in ops.

If ranked is TRUE, the source list will be ordered by rank.

registry :

the registry instance

ops :

a bitwise mangle of the requested operations.

ranked :

whether the returned list shall be returned ordered by rank

Returns :

a GList of available GrlSources. The content of the list should not be modified or freed. Use g_list_free() when done using the list. [element-type Grl.Source][transfer container]

Since 0.2.0


grl_registry_load_all_plugins ()

gboolean            grl_registry_load_all_plugins       (GrlRegistry *registry,
                                                         GError **error);

Load all the modules available in the default directory path.

The default directory path can be changed through the environment variable GRL_PLUGIN_PATH and it can contain several paths separated by ":"

registry :

the registry instance

error :

error return location or NULL to ignore

Returns :

FALSE% is all the configured plugin paths are invalid, TRUE% otherwise.

Since 0.2.0


grl_registry_load_plugin ()

gboolean            grl_registry_load_plugin            (GrlRegistry *registry,
                                                         const gchar *library_filename,
                                                         GError **error);

Loads a module from shared object file stored in path

registry :

the registry instance

library_filename :

the path to the so file

error :

error return location or NULL to ignore

Returns :

TRUE if the module is loaded correctly

Since 0.2.0


grl_registry_load_plugin_by_id ()

gboolean            grl_registry_load_plugin_by_id      (GrlRegistry *registry,
                                                         const gchar *plugin_id,
                                                         GError **error);

Loads plugin identified by plugin_id.

This requires the XML plugin information file to define a "module" key with the name of the module that provides the plugin or the absolute path of the actual module file.

registry :

the registry instance

plugin_id :

plugin identifier

error :

error return location or NULL to ignore

Returns :

TRUE if the plugin is loaded correctly

Since 0.2.0


grl_registry_load_plugin_directory ()

gboolean            grl_registry_load_plugin_directory  (GrlRegistry *registry,
                                                         const gchar *path,
                                                         GError **error);

Loads a set of modules from directory in path which contains a group shared object files.

registry :

the registry instance

path :

the path to the directory

error :

error return location or NULL to ignore

Returns :

TRUE if the directory is valid.

Since 0.2.0


grl_registry_lookup_metadata_key ()

GrlKeyID            grl_registry_lookup_metadata_key    (GrlRegistry *registry,
                                                         const gchar *key_name);

Look up for the metadata key with name key_name.

registry :

the registry instance

key_name :

the key name

Returns :

The metadata key, or GRL_METADATA_KEY_INVALID if not found

Since 0.2.0


grl_registry_lookup_metadata_key_desc ()

const gchar *       grl_registry_lookup_metadata_key_desc
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);

Returns key description.

registry :

the registry instance

key :

a metadata key

Returns :

metadata key description, or NULL if not found

Since 0.2.0


grl_registry_lookup_metadata_key_name ()

const gchar *       grl_registry_lookup_metadata_key_name
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);

Returns key name.

registry :

the registry instance

key :

a metadata key

Returns :

metadata key name, or NULL if not found

Since 0.2.0


grl_registry_lookup_metadata_key_relation ()

const GList *       grl_registry_lookup_metadata_key_relation
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);

Look up the list of keys that have a relation with key.

key is included in that list.

registry :

the registry instance

key :

a metadata key

Returns :

a GList of related keys, or NULL if key is invalid. [element-type GrlKeyID][transfer none]

Since 0.2.0


grl_registry_lookup_metadata_key_type ()

GType               grl_registry_lookup_metadata_key_type
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key);

Returns key expected value type.

registry :

the registry instance

key :

a metadata key

Returns :

metadata key type, or G_TYPE_INVALID if not found

Since 0.2.0


grl_registry_lookup_plugin ()

GrlPlugin *         grl_registry_lookup_plugin          (GrlRegistry *registry,
                                                         const gchar *plugin_id);

This function will search and retrieve a plugin given its identifier.

registry :

the registry instance

plugin_id :

the id of a plugin

Returns :

The plugin found. [transfer none]

Since 0.2.0


grl_registry_lookup_source ()

GrlSource *         grl_registry_lookup_source          (GrlRegistry *registry,
                                                         const gchar *source_id);

This function will search and retrieve a source given its identifier.

registry :

the registry instance

source_id :

the id of a source

Returns :

The source found. [transfer none]

Since 0.2.0


grl_registry_metadata_key_validate ()

gboolean            grl_registry_metadata_key_validate  (GrlRegistry *registry,
                                                         GrlKeyID key,
                                                         GValue *value);

Validates value content complies with the key specification. That is, it has the expected type, and value are within the range specified in key (for integer values).

registry :

the registry instance

key :

a metadata key

value :

value to be validate

Returns :

TRUE if complies

Since 0.2.0


grl_registry_register_metadata_key ()

GrlKeyID            grl_registry_register_metadata_key  (GrlRegistry *registry,
                                                         GParamSpec *param_spec,
                                                         GError **error);

Registers a metadata key

registry :

The plugin registry

param_spec :

The definition of the key to register

error :

error return location or NULL to ignore

Returns :

The GrlKeyID registered.

Since 0.2.0


grl_registry_register_metadata_key_relation ()

void                grl_registry_register_metadata_key_relation
                                                        (GrlRegistry *registry,
                                                         GrlKeyID key1,
                                                         GrlKeyID key2);

Creates a relation between key1 and key2, meaning that the values of both keys are somehow related.

One example of a relation would be the one between the URI of a media resource and its mime-type: they are both tied together and one does not make sense without the other.

Relations between keys allow the framework to provide all the data that is somehow related when any of the related keys are requested.

registry :

the plugin registry

key1 :

key involved in relationship

key2 :

key involved in relationship

Since 0.2.0


grl_registry_register_source ()

gboolean            grl_registry_register_source        (GrlRegistry *registry,
                                                         GrlPlugin *plugin,
                                                         GrlSource *source,
                                                         GError **error);

Register a source in the registry with the given plugin information

registry :

the registry instance

plugin :

the plugin which owns the source

source :

the source to register

error :

error return location or NULL to ignore

Returns :

TRUE if success, FALSE% otherwise.

Since 0.2.0


grl_registry_unload_plugin ()

gboolean            grl_registry_unload_plugin          (GrlRegistry *registry,
                                                         const gchar *plugin_id,
                                                         GError **error);

Unload from memory a module identified by plugin_id. This means call the module's deinit function.

registry :

the registry instance

plugin_id :

the identifier of the plugin

error :

error return location or NULL to ignore

Returns :

TRUE% on success.

Since 0.2.0


grl_registry_unregister_source ()

gboolean            grl_registry_unregister_source      (GrlRegistry *registry,
                                                         GrlSource *source,
                                                         GError **error);

Removes the source from the registry hash table

registry :

the registry instance

source :

the source to unregister

error :

error return location or NULL to ignore

Returns :

TRUE if success, FALSE% otherwise.

Since 0.2.0

Signal Details

The "source-added" signal

void                user_function                      (GrlRegistry *registry,
                                                        GrlSource   *source,
                                                        gpointer     user_data)      : Action

Signals that a source has been added to the registry.

registry :

the registry

source :

the source that has been added

user_data :

user data set when the signal handler was connected.

Since 0.2.0


The "source-removed" signal

void                user_function                      (GrlRegistry *registry,
                                                        GrlSource   *source,
                                                        gpointer     user_data)      : Action

Signals that a source has been removed from the registry.

registry :

the registry

source :

the source that has been removed

user_data :

user data set when the signal handler was connected.

Since 0.2.0

See Also

GrlPlugin, GrlSource