RCLibPlugin

RCLibPlugin — The plug-in support system

Synopsis

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

Object Hierarchy

  GObject
   +----RCLibPlugin
  GBoxed
   +----RCLibPluginData

Signals

  "loaded"                                         : Run First
  "registered"                                     : Run First
  "shutdown"                                       : Run First
  "unloaded"                                       : Run First
  "unregistered"                                   : Run First

Description

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.

Details

RCLIB_PLUGIN_MAGIC

#define RCLIB_PLUGIN_MAGIC 0x20120909

RCLIB_PLUGIN_MAJOR_VERSION

#define RCLIB_PLUGIN_MAJOR_VERSION 2

RCLIB_PLUGIN_MINOR_VERSION

#define RCLIB_PLUGIN_MINOR_VERSION 0

struct RCLibPlugin

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 RCLibPluginClass

struct RCLibPluginClass {
};

RCLibPlugin class.


struct RCLibPluginData

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 native;

whether the plug-in is a native C/C++ module

gboolean loaded;

whether the plug-in is loaded

gpointer handle;

the handle of the plug-in

gchar *path;

the file path of the plug-in

RCLibPluginInfo *info;

the information data (RCLibPluginInfo) of the plug-in

gchar *error;

the error message in the initialization progress

gboolean unloadable;

whether the plug-in is not loadable

GSList *dependent_list;

a list of the dependent plug-ins

gpointer extra;

extra data

gpointer ipc_data;

(not used now)

struct RCLibPluginInfo

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;
};

guint32 magic;

the magic number, should be equal to RCLIB_PLUGIN_MAGIC

guint32 major_version;

the major version of the plug-in support module, should be equal to RCLIB_PLUGIN_MAJOR_VERSION

guint32 minor_version;

the minor version of the plug-in support module, should be equal to RCLIB_PLUGIN_MINOR_VERSION

RCLibPluginType type;

the type of the plug-in

gchar *id;

the ID of the plug-in, should be unique

gchar *name;

the name of the plug-in

gchar *version;

the version of the plug-in

gchar *description;

the description of the plug-in

gchar *author;

the author of the plug-in

gchar *homepage;

the homepage URL of the plug-in

load ()

the load function of the plug-in

unload ()

the unload function of the plug-in

destroy ()

the destroy function of the plug-in

configure ()

the configure function of the plug-in

gchar **depends;

the depend array of the plug-in

gpointer extra_info;

the extra information data

struct RCLibPluginLoaderInfo

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  *extensions;

a string list for the extension of plug-in files which will be supported by the loader

probe ()

the probe function for the loader

load ()

the load function for the loader

unload ()

the unload function for the loader

destroy ()

the destroy function for the loader

enum RCLibPluginType

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.

RCLIB_PLUGIN_TYPE_UNKNOWN

unknown plug-in type

RCLIB_PLUGIN_TYPE_MODULE

normal plug-in type

RCLIB_PLUGIN_TYPE_LOADER

plug-in loader type

rclib_plugin_data_ref ()

RCLibPluginData *   rclib_plugin_data_ref               (RCLibPluginData *plugin);

Increase the reference count of plug-data by 1.

plugin :

the plug-in data

Returns :

The plug-in data. [transfer none]

rclib_plugin_data_unref ()

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.

plugin :

the plug-in data

rclib_plugin_destroy ()

void                rclib_plugin_destroy                (RCLibPluginData *plugin);

Exit the plug-in and destroy the plug-in data.

plugin :

the plug-in data

rclib_plugin_destroy_all ()

void                rclib_plugin_destroy_all            ();

Destroy all plug-ins in the player.


rclib_plugin_exit ()

void                rclib_plugin_exit                   ();

Unload the plug-in support system instance.


rclib_plugin_foreach ()

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.

func :

the function to call for each key/value pair. [scope call]

data :

user data to pass to the function

rclib_plugin_get_instance ()

GObject *           rclib_plugin_get_instance           ();

Get the running RCLibPlugin instance.

Returns :

The running instance. [transfer none]

rclib_plugin_get_keyfile ()

GKeyFile *          rclib_plugin_get_keyfile            ();

Get the GKeyFile configure data of the plug-ins.

Returns :

The configure data.

rclib_plugin_init ()

gboolean            rclib_plugin_init                   (const gchar *file);

Initialize the plug-in support system instance.

file :

the configure file path

Returns :

Whether the initialization succeeded.

rclib_plugin_is_loaded ()

gboolean            rclib_plugin_is_loaded              (RCLibPluginData *plugin);

Check whether the plug-in is loaded.

plugin :

the plug-in data

Returns :

Whether the plug-in is loaded.

rclib_plugin_is_registed ()

gboolean            rclib_plugin_is_registed            (const gchar *id);

Check whether the given ID is registered in the plug-in table.

id :

the ID of the plug-in

Returns :

Whether the given ID is registered.

rclib_plugin_load ()

gboolean            rclib_plugin_load                   (RCLibPluginData *plugin);

Load and run the plug-in.

plugin :

the plug-in data

Returns :

Whether the plug-in is loaded successfully.

rclib_plugin_load_from_configure ()

void                rclib_plugin_load_from_configure    ();

Load registered plug-ins enabled in the configure file.


rclib_plugin_load_from_dir ()

guint               rclib_plugin_load_from_dir          (const gchar *dirname);

Load plug-in files from given directory path, and register them.

dirname :

the path of the directory which contains the plug-in files

Returns :

Loaded plug-in number.

rclib_plugin_lookup ()

RCLibPluginData *   rclib_plugin_lookup                 (const gchar *id);

Lookup a plug-in in the registered plug-in table by the given ID.

id :

the ID of the plug-in

Returns :

The plug-in data, NULL if not found.

rclib_plugin_probe ()

RCLibPluginData *   rclib_plugin_probe                  (const gchar *filename);

Probe the plug-in file.

filename :

file path to the plug-in file

Returns :

The plug-in data, NULL if the probe operation failed.

rclib_plugin_register ()

gboolean            rclib_plugin_register               (RCLibPluginData *plugin);

Register the plug-in to the player.

plugin :

the plug-in data

Returns :

Whether the register operation succeeded.

rclib_plugin_reload ()

gboolean            rclib_plugin_reload                 (RCLibPluginData *plugin);

Reload and restart the plug-in.

plugin :

the plug-in data

Returns :

Whether the plug-in is reloaded successfully.

rclib_plugin_signal_connect ()

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.

name :

the name of the signal

callback :

the the GCallback to connect. [scope call]

data :

the user data

Returns :

The handler ID.

rclib_plugin_signal_disconnect ()

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 :

handler id of the handler to be disconnected

rclib_plugin_unload ()

gboolean            rclib_plugin_unload                 (RCLibPluginData *plugin);

Stop and unload the plug-in.

plugin :

the plug-in data

Returns :

Whether the plug-in is unloaded successfully.

Signal Details

The "loaded" signal

void                user_function                      (RCLibPlugin *plugin,
                                                        gpointer     data,
                                                        gpointer     user_data)      : Run First

The ::loaded signal is emitted when a plug-in is loaded.

plugin :

the RCLibPlugin that received the signal

data :

the plug-in data (RCLibPluginData)

user_data :

user data set when the signal handler was connected.

The "registered" signal

void                user_function                      (RCLibPlugin *plugin,
                                                        gpointer     data,
                                                        gpointer     user_data)      : Run First

The ::registered signal is emitted when a new plug-in registered.

plugin :

the RCLibPlugin that received the signal

data :

the plug-in data (RCLibPluginData)

user_data :

user data set when the signal handler was connected.

The "shutdown" signal

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

plugin :

the RCLibPlugin that received the signal

user_data :

user data set when the signal handler was connected.

The "unloaded" signal

void                user_function                      (RCLibPlugin *plugin,
                                                        gpointer     data,
                                                        gpointer     user_data)      : Run First

The ::unloaded signal is emitted when a plug-in is unloaded.

plugin :

the RCLibPlugin that received the signal

data :

the plug-in data (RCLibPluginData)

user_data :

user data set when the signal handler was connected.

The "unregistered" signal

void                user_function                      (RCLibPlugin *plugin,
                                                        gchar       *id,
                                                        gpointer     user_data)      : Run First

The ::unregistered signal is emitted when a plug-in is unregistered.

plugin :

the RCLibPlugin that received the signal

id :

the ID of the plug-in

user_data :

user data set when the signal handler was connected.