EthosManager

EthosManager — plugin management during runtime

Synopsis

#define             ETHOS_MANAGER_CONST                 (obj)
                    EthosManagerPrivate;
                    EthosManager;
EthosManager*       ethos_manager_new                   (void);
EthosManager*       ethos_manager_new_full              (const gchar *app_name,
                                                         gchar **plugin_dirs);
void                ethos_manager_initialize            (EthosManager *manager);
void                ethos_manager_unload                (EthosManager *manager);
gboolean            ethos_manager_load_plugin           (EthosManager *manager,
                                                         EthosPluginInfo *plugin_info,
                                                         GError **error);
gboolean            ethos_manager_unload_plugin         (EthosManager *manager,
                                                         EthosPluginInfo *plugin_info,
                                                         GError **error);
GList*              ethos_manager_get_plugin_info       (EthosManager *manager);
EthosPlugin*        ethos_manager_get_plugin            (EthosManager *manager,
                                                         EthosPluginInfo *plugin_info);
GList*              ethos_manager_get_plugin_loaders    (EthosManager *manager);
const gchar**       ethos_manager_get_plugin_dirs       (EthosManager *manager);
void                ethos_manager_set_plugin_dirs       (EthosManager *manager,
                                                         gchar **plugin_dirs);
const gchar*        ethos_manager_get_app_name          (EthosManager *manager);
void                ethos_manager_set_app_name          (EthosManager *manager,
                                                         const gchar *app_name);

Object Hierarchy

  GObject
   +----EthosManager

Signals

  "initialized"                                    : Run First
  "plugin-loaded"                                  : Run First
  "plugin-unloaded"                                : Run First

Description

The EthosManager is responsible for managing plugins during runtime. It can be used to load and unload plugins as well as configure where and how plugins should be loaded.

During runtime, the app_name and plugin_dirs should both be set. The app_name is used to derive the plugin filenames and how to parse them. The plugin_dirs are used to locate plugins.

Details

ETHOS_MANAGER_CONST()

#define ETHOS_MANAGER_CONST(obj)	(G_TYPE_CHECK_INSTANCE_CAST ((obj), ETHOS_TYPE_MANAGER, EthosManager const))

obj :

EthosManagerPrivate

typedef struct _EthosManagerPrivate EthosManagerPrivate;

EthosManager

typedef struct _EthosManager EthosManager;

ethos_manager_new ()

EthosManager*       ethos_manager_new                   (void);

Creates a new instance of EthosManager. There should only be one of these created per process.

Returns :

 the newly created EthosManager instance.

ethos_manager_new_full ()

EthosManager*       ethos_manager_new_full              (const gchar *app_name,
                                                         gchar **plugin_dirs);

Creates a new EthosManager instance and sets the application name and plugin directories to traverse to locate plugins.

app_name :

 The name of the application (Capitalized)

plugin_dirs :

 An array of strings containing directories to locate plugins

Returns :

 The newly created EthosManager instance.

ethos_manager_initialize ()

void                ethos_manager_initialize            (EthosManager *manager);

Initialize the plugin manager. This will result in the manager looking for all of the available plugins that it can find in the registered plugin directories.

manager :

 An EthosManager

ethos_manager_unload ()

void                ethos_manager_unload                (EthosManager *manager);

Unloads all of the plugins.

manager :

 An EthosManager

ethos_manager_load_plugin ()

gboolean            ethos_manager_load_plugin           (EthosManager *manager,
                                                         EthosPluginInfo *plugin_info,
                                                         GError **error);

Attempts to load a plugin using the EthosPluginInfo.

manager :

 An EthosManager

plugin_info :

 An EthosPluginInfo

error :

 A location for a GError

Returns :

 TRUE if the plugin was loaded. error is set in case of failure.

ethos_manager_unload_plugin ()

gboolean            ethos_manager_unload_plugin         (EthosManager *manager,
                                                         EthosPluginInfo *plugin_info,
                                                         GError **error);

Attempts to unload the plugin that was created using plugin_info.

manager :

 An EthosManager

plugin_info :

 An EthosPluginInfo

error :

 A location for a GError or NULL

Returns :

 TRUE if the plugin was unloaded. error is set in case of failure.

ethos_manager_get_plugin_info ()

GList*              ethos_manager_get_plugin_info       (EthosManager *manager);

Retreives the list of EthosPluginInfo that were discovered.

manager :

 An EthosManager

Returns :

 A GList of EthosPluginInfo which should be freed using g_list_free().

ethos_manager_get_plugin ()

EthosPlugin*        ethos_manager_get_plugin            (EthosManager *manager,
                                                         EthosPluginInfo *plugin_info);

Retrieves the created instance of the plugin defined by plugin_info. If no instance of the plugin has been created, then NULL is returned.

manager :

 An EthosManager

plugin_info :

 An EthosPluginInfo

Returns :

 The EthosPlugin instance or NULL

ethos_manager_get_plugin_loaders ()

GList*              ethos_manager_get_plugin_loaders    (EthosManager *manager);

Retreives a list of EthosPluginLoaders that were discovered when the application was initialized.

manager :

 An EthosManager

Returns :

 A GList of EthosPluginLoaders. The list should be freed using g_list_free().

ethos_manager_get_plugin_dirs ()

const gchar**       ethos_manager_get_plugin_dirs       (EthosManager *manager);

Retrieves the list of plugin directories that are traversed when looking to load plugins.

manager :

 An EthosManager

Returns :

 a NULL terminated list of strings containing directories that will be traversed to locate plugins. This reslut should never be modified or freed.

ethos_manager_set_plugin_dirs ()

void                ethos_manager_set_plugin_dirs       (EthosManager *manager,
                                                         gchar **plugin_dirs);

Sets the list of directories to use for locating plugins.

manager :

 An EthosManager

plugin_dirs :

 A NULL terminated list of strings of directories

ethos_manager_get_app_name ()

const gchar*        ethos_manager_get_app_name          (EthosManager *manager);

Retrieves the app-name that the EthosManager should use.

manager :

 An EthosManager

Returns :

 the configured app name used for plugins or NULL

ethos_manager_set_app_name ()

void                ethos_manager_set_app_name          (EthosManager *manager,
                                                         const gchar *app_name);

Sets the app name used for the application. This should be a single word to simplify the plugin development process. The app name is used inside the plugin description files for the group prefix as well as in the name of the file.

For example, an application named "Ethos" would have the group [Ethos Plugin] in the plugin description file which would be named myplugin.ethos-plugin.

manager :

 An EthosManager

app_name :

 A single-worded name for the application

Signal Details

The "initialized" signal

void                user_function                      (EthosManager *manager,
                                                        gpointer      user_data)      : Run First

The initialized signal is emmitted after the manager has completed initializing. This is a good place to load the plugins you want loaded on startup.

manager :

 An EthosManager

user_data :

 user data set when the signal handler was connected.

The "plugin-loaded" signal

void                user_function                      (EthosManager    *manager,
                                                        EthosPluginInfo *plugin_info,
                                                        gpointer         user_data)        : Run First

The plugin-loaded signal is emitted when a plugin has been successfully loaded.

manager :

 An EthosManager

plugin_info :

 An EthosPluginInfo

user_data :

 user data set when the signal handler was connected.

The "plugin-unloaded" signal

void                user_function                      (EthosManager    *manager,
                                                        EthosPluginInfo *plugin_info,
                                                        gpointer         user_data)        : Run First

The plugin-loaded signal is emitted when a plugin has been successfully unloaded.

manager :

 An EthosManager

plugin_info :

 An EthosPluginInfo

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.11