![]() |
![]() |
![]() |
Grilo Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Signals |
#include <grilo.h> #define GRL_PLUGIN_PATH_VAR #define GRL_PLUGIN_RANKS_VAR #define GRL_PLUGIN_REGISTER (init, deinit, id) struct GrlPluginInfo; struct GrlPluginDescriptor; enum GrlPluginRank; struct GrlPluginRegistry; struct GrlPluginRegistryClass; GrlPluginRegistry * grl_plugin_registry_get_default (void
); void grl_plugin_registry_add_directory (GrlPluginRegistry *registry
,const gchar *path
); gboolean grl_plugin_registry_load (GrlPluginRegistry *registry
,const gchar *library_filename
,GError **error
); gboolean grl_plugin_registry_load_directory (GrlPluginRegistry *registry
,const gchar *path
,GError **error
); gboolean grl_plugin_registry_unload (GrlPluginRegistry *registry
,const gchar *plugin_id
,GError **error
); gboolean grl_plugin_registry_load_all (GrlPluginRegistry *registry
,GError **error
); gboolean grl_plugin_registry_load_by_id (GrlPluginRegistry *registry
,const gchar *plugin_id
,GError **error
); gboolean grl_plugin_registry_register_source (GrlPluginRegistry *registry
,const GrlPluginInfo *plugin
,GrlMediaPlugin *source
,GError **error
); gboolean grl_plugin_registry_unregister_source (GrlPluginRegistry *registry
,GrlMediaPlugin *source
,GError **error
); GrlMediaPlugin * grl_plugin_registry_lookup_source (GrlPluginRegistry *registry
,const gchar *source_id
); GList * grl_plugin_registry_get_sources (GrlPluginRegistry *registry
,gboolean ranked
); GList * grl_plugin_registry_get_sources_by_operations (GrlPluginRegistry *registry
,GrlSupportedOps ops
,gboolean ranked
); GrlKeyID grl_plugin_registry_register_metadata_key (GrlPluginRegistry *registry
,GParamSpec *key
,GError **error
); void grl_plugin_registry_register_metadata_key_relation (GrlPluginRegistry *registry
,GrlKeyID key1
,GrlKeyID key2
); GrlKeyID grl_plugin_registry_lookup_metadata_key (GrlPluginRegistry *registry
,const gchar *key_name
); const GList * grl_plugin_registry_lookup_metadata_key_relation (GrlPluginRegistry *registry
,GrlKeyID key
); GList * grl_plugin_registry_get_metadata_keys (GrlPluginRegistry *registry
); gboolean grl_plugin_registry_add_config (GrlPluginRegistry *registry
,GrlConfig *config
,GError **error
); gboolean grl_plugin_registry_add_config_from_file (GrlPluginRegistry *registry
,const gchar *config_file
,GError **error
);
The registry holds the metadata of a set of plugins.
The GrlPluginRegistry object is a list of plugins and some functions for dealing with them. Each GrlMediaPlugin 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 GrlPluginRegistry (singleton pattern).
A GrlMediaPlugin can hold several data sources (GrlMetadataSource or GrlMediaSource), and GrlPluginRegistry shall register each one of them.
#define GRL_PLUGIN_REGISTER(init, \ deinit, \ id)
Define the boilerplate for loadable modules. Defines a new module descriptor which provides a set of GrlMediaPlugins
|
the module initialization. It shall instantiate the GrlMediaPlugins provided |
|
function to execute when the registry needs to dispose the module. [allow-none] |
|
the module identifier |
struct GrlPluginInfo { gchar *id; gchar *filename; GHashTable *optional_info; gint rank; };
This structure stores the information related to a module
gchar * |
the module identifier |
gchar * |
the filename containing the plugin |
GHashTable * |
Key/value pairs with extra information about the plugin. |
gint |
the plugin priority rank |
struct GrlPluginDescriptor { gchar *plugin_id; gboolean (*plugin_init) (GrlPluginRegistry *, const GrlPluginInfo *, GList *); void (*plugin_deinit) (void); GModule *module; };
This structure is used for the module loader
gchar * |
the module identifier |
the module initialization. It shall instantiate the GrlMediaPlugins provided | |
function to execute when the registry needs to dispose the module. | |
GModule * |
the GModule instance. |
typedef enum { GRL_PLUGIN_RANK_LOWEST = -64, GRL_PLUGIN_RANK_LOW = -32, GRL_PLUGIN_RANK_DEFAULT = 0, GRL_PLUGIN_RANK_HIGH = 32, GRL_PLUGIN_RANK_HIGHEST = 64, } GrlPluginRank;
Module priority ranks. Defines the order in which the resolver (or similar rank-picking mechanisms) will choose this plugin over an alternative one with the same function.
These constants serve as a rough guidance for defining the rank of a GrlPluginInfo. Any value is valid, including values bigger than GRL_PLUGIN_RANK_HIGHEST.
struct GrlPluginRegistryClass { GObjectClass parent_class; };
Grilo PluginRegistry class. Dynamic loader of plugins.
GObjectClass |
the parent class structure |
GrlPluginRegistry * grl_plugin_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.1.6
void grl_plugin_registry_add_directory (GrlPluginRegistry *registry
,const gchar *path
);
Set this path as part of default paths to load plugins.
|
the registry instance |
|
a path with plugins |
Since 0.1.6
gboolean grl_plugin_registry_load (GrlPluginRegistry *registry
,const gchar *library_filename
,GError **error
);
Loads a module from shared object file stored in path
|
the registry instance |
|
the path to the so file |
|
error return location or NULL to ignore |
Returns : |
TRUE if the module is loaded correctly |
Since 0.1.7
gboolean grl_plugin_registry_load_directory (GrlPluginRegistry *registry
,const gchar *path
,GError **error
);
Loads a set of modules from directory in path
which contains
a group shared object files.
|
the registry instance |
|
the path to the directory |
|
error return location or NULL to ignore |
Returns : |
TRUE if the directory is valid. |
Since 0.1.7
gboolean grl_plugin_registry_unload (GrlPluginRegistry *registry
,const gchar *plugin_id
,GError **error
);
Unload from memory a module identified by plugin_id
. This means call the
module's deinit function.
|
the registry instance |
|
the identifier of the plugin |
|
error return location or NULL to ignore |
Returns : |
TRUE % on success. |
Since 0.1.7
gboolean grl_plugin_registry_load_all (GrlPluginRegistry *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 ":"
|
the registry instance |
|
error return location or NULL to ignore |
Returns : |
FALSE % is all the configured plugin paths are invalid,
TRUE % otherwise. |
Since 0.1.1
gboolean grl_plugin_registry_load_by_id (GrlPluginRegistry *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.
|
the registry instance |
|
plugin identifier |
|
error return location or NULL to ignore |
Returns : |
TRUE if the plugin is loaded correctly |
Since 0.1.14
gboolean grl_plugin_registry_register_source (GrlPluginRegistry *registry
,const GrlPluginInfo *plugin
,GrlMediaPlugin *source
,GError **error
);
Register a source
in the registry
with the given plugin
information
|
the registry instance |
|
the descriptor of the plugin which owns the source |
|
the source to register |
|
error return location or NULL to ignore |
Returns : |
TRUE if success, FALSE % otherwise. |
Since 0.1.7
gboolean grl_plugin_registry_unregister_source (GrlPluginRegistry *registry
,GrlMediaPlugin *source
,GError **error
);
Removes the source
from the registry
hash table
|
the registry instance |
|
the source to unregister |
|
error return location or NULL to ignore |
Returns : |
TRUE if success, FALSE % otherwise. |
Since 0.1.7
GrlMediaPlugin * grl_plugin_registry_lookup_source (GrlPluginRegistry *registry
,const gchar *source_id
);
This function will search and retrieve a source given its identifier.
|
the registry instance |
|
the id of a source |
Returns : |
The source found. [transfer none] |
Since 0.1.1
GList * grl_plugin_registry_get_sources (GrlPluginRegistry *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.
|
the registry instance |
|
whether the returned list shall be returned ordered by rank |
Returns : |
a GList of
available GrlMediaPluginss. The content of the list should not be
modified or freed. Use g_list_free() when done using the list. [element-type Grl.MediaPlugin][transfer container]
|
Since 0.1.7
GList * grl_plugin_registry_get_sources_by_operations (GrlPluginRegistry *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.
|
the registry instance |
|
a bitwise mangle of the requested operations. |
|
whether the returned list shall be returned ordered by rank |
Returns : |
a GList of
available GrlMediaPluginss. The content of the list should not be
modified or freed. Use g_list_free() when done using the list. [element-type Grl.MediaPlugin][transfer container]
|
Since 0.1.7
GrlKeyID grl_plugin_registry_register_metadata_key (GrlPluginRegistry *registry
,GParamSpec *key
,GError **error
);
Registers a metadata key
|
The plugin registry |
|
The key to register |
|
error return location or NULL to ignore |
Returns : |
The GrlKeyID registered
or NULL on error. [type GObject.ParamSpec][transfer none]
|
Since 0.1.7
void grl_plugin_registry_register_metadata_key_relation (GrlPluginRegistry *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.
|
the plugin registry |
|
key involved in relationship |
|
key involved in relationship |
Since 0.1.10
GrlKeyID grl_plugin_registry_lookup_metadata_key (GrlPluginRegistry *registry
,const gchar *key_name
);
Look up for the metadata key with name key_name
.
|
the registry instance |
|
the key name |
Returns : |
The metadata key, or NULL if not found. [type GObject.ParamSpec][transfer none]
|
Since 0.1.6
const GList * grl_plugin_registry_lookup_metadata_key_relation (GrlPluginRegistry *registry
,GrlKeyID key
);
Look up the list of keys that have a relation with key
.
key
is included in that list.
|
the registry instance |
|
a metadata key |
Returns : |
a GList of
related keys, or NULL if key is invalid. [element-type GObject.ParamSpec][transfer none]
|
Since 0.1.10
GList * grl_plugin_registry_get_metadata_keys
(GrlPluginRegistry *registry
);
Returns a list with all registered keys in system.
|
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. [element-type GObject.ParamSpec][transfer container]
|
Since 0.1.6
gboolean grl_plugin_registry_add_config (GrlPluginRegistry *registry
,GrlConfig *config
,GError **error
);
Add a configuration for a plugin/source.
|
the registry instance |
|
a configuration set. [transfer full] |
|
error return location or NULL to ignore |
Since 0.1.7
gboolean grl_plugin_registry_add_config_from_file (GrlPluginRegistry *registry
,const gchar *config_file
,GError **error
);
Load plugin configurations from a .ini-like config file.
|
the registry instance |
|
a key-value file containing the configuration |
|
error return location or NULL to ignore |
Returns : |
TRUE on success |
Since 0.1.7
"source-added"
signalvoid user_function (GrlPluginRegistry *registry,
GrlMediaPlugin *plugin,
gpointer user_data) : Action
Signals that a plugin has been added to the registry.
|
the registry |
|
the plugin that has been added |
|
user data set when the signal handler was connected. |
"source-removed"
signalvoid user_function (GrlPluginRegistry *registry,
GrlMediaPlugin *plugin,
gpointer user_data) : Action
Signals that a plugin has been removed from the registry.
|
the registry |
|
the plugin that has been removed |
|
user data set when the signal handler was connected. |