| LibRhythmCat Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Signals | ||||
#include <rclib-plugin.h> #define RCLIB_PLUGIN_MAGIC #define RCLIB_PLUGIN_MAJOR_VERSION #define RCLIB_PLUGIN_MINOR_VERSION struct RCLibPlugin; struct RCLibPluginClass; struct RCLibPluginData; struct RCLibPluginInfo; struct RCLibPluginLoaderInfo; enum RCLibPluginType; RCLibPluginData * rclib_plugin_data_ref (RCLibPluginData *plugin); void rclib_plugin_data_unref (RCLibPluginData *plugin); void rclib_plugin_destroy (RCLibPluginData *plugin); void rclib_plugin_destroy_all (); void rclib_plugin_exit (); void rclib_plugin_foreach (GHFunc func,gpointer data); GObject * rclib_plugin_get_instance (); GKeyFile * rclib_plugin_get_keyfile (); gboolean rclib_plugin_init (const gchar *file); gboolean rclib_plugin_is_loaded (RCLibPluginData *plugin); gboolean rclib_plugin_is_registed (const gchar *id); gboolean rclib_plugin_load (RCLibPluginData *plugin); void rclib_plugin_load_from_configure (); guint rclib_plugin_load_from_dir (const gchar *dirname); RCLibPluginData * rclib_plugin_lookup (const gchar *id); RCLibPluginData * rclib_plugin_probe (const gchar *filename); gboolean rclib_plugin_register (RCLibPluginData *plugin); gboolean rclib_plugin_reload (RCLibPluginData *plugin); gulong rclib_plugin_signal_connect (const gchar *name,GCallback callback,gpointer data); void rclib_plugin_signal_disconnect (gulong handler_id); gboolean rclib_plugin_unload (RCLibPluginData *plugin);
"loaded" :Run First"registered" :Run First"shutdown" :Run First"unloaded" :Run First"unregistered" :Run First
The RCLibPlugin is a class which provides plug-in support. It manages all the plug-ins and plug-in loaders, and makes them usable in the player.
struct RCLibPlugin;
The plug-in support system. The contents of the RCLibPlugin structure are private and should only be accessed via the provided API.
struct RCLibPluginData {
gboolean native;
gboolean loaded;
gpointer handle;
gchar *path;
RCLibPluginInfo *info;
gchar *error;
gboolean unloadable;
GSList *dependent_list;
gpointer extra;
gpointer ipc_data;
};
The plug-in data.
gboolean |
whether the plug-in is a native C/C++ module |
gboolean |
whether the plug-in is loaded |
gpointer |
the handle of the plug-in |
gchar * |
the file path of the plug-in |
RCLibPluginInfo * |
the information data (RCLibPluginInfo) of the plug-in |
gchar * |
the error message in the initialization progress |
gboolean |
whether the plug-in is not loadable |
GSList * |
a list of the dependent plug-ins |
gpointer |
extra data |
gpointer |
(not used now) |
struct RCLibPluginInfo {
guint32 magic;
guint32 major_version;
guint32 minor_version;
RCLibPluginType type;
gchar *id;
gchar *name;
gchar *version;
gchar *description;
gchar *author;
gchar *homepage;
gboolean (*load)(RCLibPluginData *plugin);
gboolean (*unload)(RCLibPluginData *plugin);
void (*destroy)(RCLibPluginData *plugin);
gboolean (*configure)(RCLibPluginData *plugin);
gchar **depends;
gpointer extra_info;
};
| the magic number, should be equal to RCLIB_PLUGIN_MAGIC | |
| the major version of the plug-in support module, should be equal to RCLIB_PLUGIN_MAJOR_VERSION | |
| the minor version of the plug-in support module, should be equal to RCLIB_PLUGIN_MINOR_VERSION | |
RCLibPluginType |
the type of the plug-in |
gchar * |
the ID of the plug-in, should be unique |
gchar * |
the name of the plug-in |
gchar * |
the version of the plug-in |
gchar * |
the description of the plug-in |
gchar * |
the author of the plug-in |
gchar * |
the homepage URL of the plug-in |
| the load function of the plug-in | |
| the unload function of the plug-in | |
| the destroy function of the plug-in | |
| the configure function of the plug-in | |
gchar ** |
the depend array of the plug-in |
gpointer |
the extra information data |
struct RCLibPluginLoaderInfo {
const gchar * const *extensions;
gboolean (*probe)(RCLibPluginData *plugin);
gboolean (*load)(RCLibPluginData *plugin);
gboolean (*unload)(RCLibPluginData *plugin);
void (*destroy)(RCLibPluginData *plugin);
};
const gchar * const * |
a string list for the extension of plug-in files which will be supported by the loader |
| the probe function for the loader | |
| the load function for the loader | |
| the unload function for the loader | |
| the destroy function for the loader |
typedef enum {
RCLIB_PLUGIN_TYPE_UNKNOWN = 0,
RCLIB_PLUGIN_TYPE_MODULE = 1,
RCLIB_PLUGIN_TYPE_LOADER = 2
} RCLibPluginType;
The enum type for plug-in type.
RCLibPluginData * rclib_plugin_data_ref (RCLibPluginData *plugin);
Increase the reference count of plug-data by 1.
|
the plug-in data |
Returns : |
The plug-in data. [transfer none] |
void rclib_plugin_data_unref (RCLibPluginData *plugin);
Decrease the reference count of plug-data by 1, if the reference count down to zero, the data will be freed.
|
the plug-in data |
void rclib_plugin_destroy (RCLibPluginData *plugin);
Exit the plug-in and destroy the plug-in data.
|
the plug-in data |
void rclib_plugin_foreach (GHFunc func,gpointer data);
Calls the given function for each of the key/value pairs in the GHashTable which contains the plug-in data.
|
the function to call for each key/value pair. [scope call] |
|
user data to pass to the function |
GObject * rclib_plugin_get_instance ();
Get the running RCLibPlugin instance.
Returns : |
The running instance. [transfer none] |
GKeyFile * rclib_plugin_get_keyfile ();
Get the GKeyFile configure data of the plug-ins.
Returns : |
The configure data. |
gboolean rclib_plugin_init (const gchar *file);
Initialize the plug-in support system instance.
|
the configure file path |
Returns : |
Whether the initialization succeeded. |
gboolean rclib_plugin_is_loaded (RCLibPluginData *plugin);
Check whether the plug-in is loaded.
|
the plug-in data |
Returns : |
Whether the plug-in is loaded. |
gboolean rclib_plugin_is_registed (const gchar *id);
Check whether the given ID is registered in the plug-in table.
|
the ID of the plug-in |
Returns : |
Whether the given ID is registered. |
gboolean rclib_plugin_load (RCLibPluginData *plugin);
Load and run the plug-in.
|
the plug-in data |
Returns : |
Whether the plug-in is loaded successfully. |
void rclib_plugin_load_from_configure ();
Load registered plug-ins enabled in the configure file.
guint rclib_plugin_load_from_dir (const gchar *dirname);
Load plug-in files from given directory path, and register them.
|
the path of the directory which contains the plug-in files |
Returns : |
Loaded plug-in number. |
RCLibPluginData * rclib_plugin_lookup (const gchar *id);
Lookup a plug-in in the registered plug-in table by the given ID.
|
the ID of the plug-in |
Returns : |
The plug-in data, NULL if not found. |
RCLibPluginData * rclib_plugin_probe (const gchar *filename);
Probe the plug-in file.
|
file path to the plug-in file |
Returns : |
The plug-in data, NULL if the probe operation failed. |
gboolean rclib_plugin_register (RCLibPluginData *plugin);
Register the plug-in to the player.
|
the plug-in data |
Returns : |
Whether the register operation succeeded. |
gboolean rclib_plugin_reload (RCLibPluginData *plugin);
Reload and restart the plug-in.
|
the plug-in data |
Returns : |
Whether the plug-in is reloaded successfully. |
gulong rclib_plugin_signal_connect (const gchar *name,GCallback callback,gpointer data);
Connect the GCallback function to the given signal for the running instance of RCLibPlugin object.
|
the name of the signal |
|
the the GCallback to connect. [scope call] |
|
the user data |
Returns : |
The handler ID. |
void rclib_plugin_signal_disconnect (gulong handler_id);
Disconnects a handler from the running RCLibPlugin instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The handler_id becomes invalid and may be reused.
|
handler id of the handler to be disconnected |
gboolean rclib_plugin_unload (RCLibPluginData *plugin);
Stop and unload the plug-in.
|
the plug-in data |
Returns : |
Whether the plug-in is unloaded successfully. |
"loaded" signalvoid user_function (RCLibPlugin *plugin,
gpointer data,
gpointer user_data) : Run First
The ::loaded signal is emitted when a plug-in is loaded.
|
the RCLibPlugin that received the signal |
|
the plug-in data (RCLibPluginData) |
|
user data set when the signal handler was connected. |
"registered" signalvoid user_function (RCLibPlugin *plugin,
gpointer data,
gpointer user_data) : Run First
The ::registered signal is emitted when a new plug-in registered.
|
the RCLibPlugin that received the signal |
|
the plug-in data (RCLibPluginData) |
|
user data set when the signal handler was connected. |
"shutdown" signalvoid user_function (RCLibPlugin *plugin,
gpointer user_data) : Run First
The ::shutdown signal is emitted when the plug-in support module is going to be shut down, so plug-in should save their configure data when receive this signal.
|
the RCLibPlugin that received the signal |
|
user data set when the signal handler was connected. |
"unloaded" signalvoid user_function (RCLibPlugin *plugin,
gpointer data,
gpointer user_data) : Run First
The ::unloaded signal is emitted when a plug-in is unloaded.
|
the RCLibPlugin that received the signal |
|
the plug-in data (RCLibPluginData) |
|
user data set when the signal handler was connected. |
"unregistered" signalvoid user_function (RCLibPlugin *plugin,
gchar *id,
gpointer user_data) : Run First
The ::unregistered signal is emitted when a plug-in is unregistered.
|
the RCLibPlugin that received the signal |
|
the ID of the plug-in |
|
user data set when the signal handler was connected. |