GrlRegistry: Grilo Reference Manual

GrlRegistry

GrlRegistry — Grilo plugins loader and manager

Functions

gboolean	grl_registry_add_config ()
gboolean	grl_registry_add_config_from_file ()
gboolean	grl_registry_add_config_from_resource ()
void	grl_registry_add_directory ()
GrlRegistry *	grl_registry_get_default ()
GList *	grl_registry_get_metadata_keys ()
GList *	grl_registry_get_plugins ()
GList *	grl_registry_get_sources ()
GList *	grl_registry_get_sources_by_operations ()
gboolean	grl_registry_load_all_plugins ()
gboolean	grl_registry_load_plugin ()
gboolean	grl_registry_load_plugin_directory ()
gboolean	grl_registry_load_plugin_from_desc ()
GrlKeyID	grl_registry_lookup_metadata_key ()
const gchar *	grl_registry_lookup_metadata_key_desc ()
const gchar *	grl_registry_lookup_metadata_key_name ()
const GList *	grl_registry_lookup_metadata_key_relation ()
GType	grl_registry_lookup_metadata_key_type ()
GrlPlugin *	grl_registry_lookup_plugin ()
GrlSource *	grl_registry_lookup_source ()
gboolean	grl_registry_metadata_key_validate ()
GrlKeyID	grl_registry_register_metadata_key ()
gboolean	grl_registry_register_source ()
gboolean	grl_registry_unload_plugin ()
gboolean	grl_registry_unregister_source ()

Signals

void	metadata-key-added	Action
void	source-added	Action
void	source-removed	Action

Types and Values

enum	GrlRank
struct	GrlRegistry
struct	GrlRegistryClass
struct	GrlPluginDescriptor
#define	GRL_PLUGIN_LIST_VAR
#define	GRL_PLUGIN_PATH_VAR
#define	GRL_PLUGIN_RANKS_VAR

Object Hierarchy

    GObject
    ╰── GrlRegistry

Includes

#include <grilo.h>

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.

Functions

grl_registry_add_config ()

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

Add a configuration for a plugin/source.

Parameters

registry	the registry instance
config	a configuration set.	[transfer full]
error	error return location or `NULL` to ignore

Returns

TRUE on success

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.

Parameters

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_config_from_resource ()

gboolean
grl_registry_add_config_from_resource (GrlRegistry *registry,
                                       const gchar *resource_path,
                                       GError **error);

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

Parameters

registry	the registry instance
resource_path	a key-value file containing the configuration
error	error return location or `NULL` to ignore

Returns

TRUE on success

Since: 0.2.8

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.

Parameters

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.

Parameters

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.

Parameters

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 GrlPlugin][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.

Parameters

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 GrlSource][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.

Parameters

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 GrlSource][transfer container]

Since: 0.2.0

grl_registry_load_all_plugins ()

gboolean
grl_registry_load_all_plugins (GrlRegistry *registry,
                               gboolean activate,
                               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 ":"

Parameters

registry	the registry instance
activate	`TRUE` if plugins must be activated after loading
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

Parameters

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

Parameters

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_load_plugin_from_desc ()

gboolean
grl_registry_load_plugin_from_desc (GrlRegistry *registry,
                                    GrlPluginDescriptor *plugin_desc,
                                    GError **error);

Loads the grilo plugin defined by plugin_desc . This is used to load plugins that aren't shared libraries, and are built into applications.

Example 1.

Minimal example for loading a builtin plugin, in C.

    static GrlPluginDescriptor descriptor = {
      .plugin_id = "grl-example",
      .plugin_init = grl_example_plugin_init,
    };

    grl_registry_load_plugin_from_desc (registry, &descriptor, &error);

[skip]

Parameters

registry	the registry instance
plugin_desc	the GrlPluginDescriptor for the plugin
error	error return location or `NULL` to ignore

Returns

TRUE if the plugin is initialised correctly

Since: 0.3.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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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,
                                    GrlKeyID bind_key,
                                    GError **error);

Registers a new metadata key, creating a relation between the new key and bind_key .

Two keys are related when 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.

Parameters

registry	The plugin registry
param_spec	The definition of the key to register.	[transfer full]
bind_key	The key the new key is bind to, or GRL_METADATA_KEY_INVALID if it is not bound.
error	error return location or `NULL` to ignore

Returns

The GrlKeyID registered.

Since: 0.3.0

grl_registry_register_source ()

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

Parameters

registry	the registry instance
plugin	the plugin which owns the source
source	the source to register.	[transfer full]
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.

Parameters

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

Parameters

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

Types and Values

enum GrlRank

Source priority ranks. Defines the order in which the resolver (or similar rank-picking mechanisms) will choose this source over an alternative one with the same function.

These constants serve as a rough guidance for defining the rank of a GrlSource. Any value is valid, including values bigger than GRL_RANK_HIGHEST.

Members

GRL_RANK_LOWEST	will be chosen last or not at all
GRL_RANK_LOW	unlikely to be chosen
GRL_RANK_DEFAULT	likely to be chosen
GRL_RANK_HIGH	will be chosen
GRL_RANK_HIGHEST	will be chosen first

struct GrlRegistry

struct GrlRegistry;

struct GrlRegistryClass

struct GrlRegistryClass {
  GObjectClass parent_class;
};

Grilo Registry class. Dynamic loader of plugins.

Members

struct GrlPluginDescriptor

struct GrlPluginDescriptor {
  gint major_version;
  gint minor_version;
  gchar *id;
  gchar *name;
  gchar *description;
  gchar *author;
  gchar *version;
  gchar *license;
  gchar *site;

  GrlPluginInitFunc init;
  GrlPluginDeinitFunc deinit;
  GrlPluginRegisterKeysFunc register_keys;
};

This structure is used for the module loader

Members

gint `major_version`;	the major version number of core that plugin was compiled for
gint `minor_version`;	the minor version number of core that plugin was compiled for
gchar *`id`;	the plugin identifier
gchar *`name`;	name of plugin
gchar *`description`;	description of plugin
gchar *`author`;	author of plugin
gchar *`version`;	version of plugin
gchar *`license`;	license of plugin
gchar *`site`;	URL to provider of plugin
GrlPluginInitFunc `init`;
GrlPluginDeinitFunc `deinit`;
GrlPluginRegisterKeysFunc `register_keys`;

Since: 0.3.0

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"

Signal Details

The `“metadata-key-added”` signal

void
user_function (GrlRegistry *registry,
               gchar       *key,
               gpointer     user_data)

Signals that a new metadata key has been registered.

Parameters

registry	the registry
key	the name of the new key added
user_data	user data set when the signal handler was connected.

Flags: Action

Since: 0.2.10

The `“source-added”` signal

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

Signals that a source has been added to the registry.

Parameters

registry	the registry
source	the source that has been added
user_data	user data set when the signal handler was connected.

Flags: Action

Since: 0.2.0

The `“source-removed”` signal

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

Signals that a source has been removed from the registry.

Parameters

registry	the registry
source	the source that has been removed
user_data	user data set when the signal handler was connected.

Flags: Action

Since: 0.2.0