EthosManager

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