GrlRegistry: Grilo Reference Manual

## GrlRegistry

GrlRegistry — Grilo plugins loader and manager

## Functions

#define | GRL_PLUGIN_DEFINE()
gboolean | grl_registry_activate_all_plugins ()
gboolean | grl_registry_activate_plugin_by_id ()
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_PLUGIN_DEFINE()

    #define             GRL_PLUGIN_DEFINE(major, minor, id, name, description, author, version, license, site, init, deinit, register_keys)

#### Parameters

major | the major version number of core that plugin was compiled for, as an integer |
minor | the minor version number of core that plugin was compiled for, as an integer |
id | the plugin identifier |
name | name of plugin |
description | description of plugin |
author | author of plugin |
version | version of plugin |
license | license of plugin |
site | URL to provider of plugin |
init | the module initialization. It shall instantiate the GrlPlugins provided |
deinit | function to execute when the registry needs to dispose the module. | [allow-none]
register_keys | function to execute before loading the plugin. It's aim is to register new keys. | [allow-none]

Since: 0.3.0

### grl_registry_activate_all_plugins ()

    gboolean
    grl_registry_activate_all_plugins (GrlRegistry *registry);

Activate all the plugins loaded.

#### Parameters

registry | the registry instace |

#### Returns

`TRUE` if some plugin has been activated

Since: 0.3.0

### grl_registry_activate_plugin_by_id ()

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

Activates plugin identified by `plugin_id` .

#### Parameters

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

### 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);

Register a `source` in the `registry` with the given `plugin` information

#### 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`; | the module initialization. It shall instantiate the GrlPlugins provided |
GrlPluginDeinitFunc `deinit`; | function to execute when the registry needs to dispose the module. |
GrlPluginRegisterKeysFunc `register_keys`; | function to execute before loading the plugin. It's aim is to register new 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,
                   char        *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

## See Also

GrlPlugin, GrlSource