EthosPluginInfo

## EthosPluginInfo EthosPluginInfo — plugin description during runtime |

## Synopsis

    #define             ETHOS_PLUGIN_INFO_CONST             (obj)
                        EthosPluginInfoPrivate;
                        EthosPluginInfo;
    EthosPluginInfo*    ethos_plugin_info_new               (void);
    gboolean            ethos_plugin_info_load_from_file    (EthosPluginInfo *plugin_info,
                                                             const gchar *group,
                                                             const gchar *filename,
                                                             GError **error);
    gboolean            ethos_plugin_info_load_from_key_file
                                                            (EthosPluginInfo *plugin_info,
                                                             const gchar *group,
                                                             GKeyFile *key_file,
                                                             GError **error);
    gboolean            ethos_plugin_info_load_from_data    (EthosPluginInfo *plugin_info,
                                                             const gchar *group,
                                                             const gchar *data,
                                                             gsize length,
                                                             GError **error);
    const gchar*        ethos_plugin_info_get_id            (EthosPluginInfo *plugin_info);
    void                ethos_plugin_info_set_id            (EthosPluginInfo *plugin_info,
                                                             const gchar *id);
    const gchar*        ethos_plugin_info_get_filename      (EthosPluginInfo *plugin_info);
    void                ethos_plugin_info_set_filename      (EthosPluginInfo *plugin_info,
                                                             const gchar *filename);
    const gchar*        ethos_plugin_info_get_name          (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_module        (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_loader        (EthosPluginInfo *plugin_info);
    gchar**             ethos_plugin_info_get_authors       (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_description   (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_copyright     (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_website       (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_version       (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_dependencies  (EthosPluginInfo *plugin_info);
    const gchar*        ethos_plugin_info_get_icon_name     (EthosPluginInfo *plugin_info);
    gboolean            ethos_plugin_info_get_active        (EthosPluginInfo *plugin_info);
    void                ethos_plugin_info_set_active        (EthosPluginInfo *plugin_info,
                                                             gboolean active);
    guint               ethos_plugin_info_get_iage          (EthosPluginInfo *plugin_info);
    gboolean            ethos_plugin_info_has_errors        (EthosPluginInfo *plugin_info);
    GList*              ethos_plugin_info_get_errors        (EthosPluginInfo *plugin_info);

## Object Hierarchy

      GObject
       +----EthosPluginInfo

## Properties

      "active"                   gboolean              : Read
      "authors"                  GStrv*                : Read
      "copyright"                gchar*                : Read
      "dependencies"             gchar*                : Read
      "description"              gchar*                : Read
      "filename"                 gchar*                : Read / Write
      "icon-name"                gchar*                : Read
      "id"                       gchar*                : Read / Write
      "loader"                   gchar*                : Read
      "module"                   gchar*                : Read
      "name"                     gchar*                : Read
      "version"                  gchar*                : Read
      "website"                  gchar*                : Read

## Signals

      "loaded"                                         : Run First
      "unloaded"                                       : Run First

## Description

EthosPluginInfo encapsulates information about a plugin during runtime. The data for an EthosPluginInfo is read from a plugin description file such as "my-plugin.example-plugin". This includes information about the plugin module to load, what EthosPluginLoader should be used, the author, description, and the icon for the plugin.

The naming of the plugin description files is derived from the name of the application or the name set using `ethos_manager_set_app_name()`. It is all lowercase and is named such as "name.appname-plugin" where appname is lowercase. Therfore, if the application was named "Marina" and the plugin was named "foo", an apt name for the description file would be "foo.marina-plugin".

The plugin description file consists of a simple GKeyFile format. The header for key-file is also derived from the application name. Therefore, if the application was named "Marina", the header for the key file would be "[Marina Plugin]".

A plugin for an application named "Sample" may look like:

    # example.sample-plugin
    [Sample Plugin]
    Name=Example
    Loader=python
    Module=example
    IAge=1
    Authors=Foo;Bar;Baz
    Copyright=MIT X11
    Website=http://example.com

## Details

### ETHOS_PLUGIN_INFO_CONST()

    #define ETHOS_PLUGIN_INFO_CONST(obj)		(G_TYPE_CHECK_INSTANCE_CAST ((obj), ETHOS_TYPE_PLUGIN_INFO, EthosPluginInfo const))

`obj` : |

### EthosPluginInfoPrivate

    typedef struct _EthosPluginInfoPrivate EthosPluginInfoPrivate;

### EthosPluginInfo

    typedef struct _EthosPluginInfo EthosPluginInfo;

### ethos_plugin_info_new ()

    EthosPluginInfo*    ethos_plugin_info_new               (void);

Creates a new EthosPluginInfo instance.

Returns : | The newly created EthosPluginInfo instance.

### ethos_plugin_info_load_from_file ()

    gboolean            ethos_plugin_info_load_from_file    (EthosPluginInfo *plugin_info,
                                                             const gchar *group,
                                                             const gchar *filename,
                                                             GError **error);

Loads the plugin information found within `filename`. If there is an error, `FALSE` is returned and `error` will be set.

`plugin_info` : | An EthosPluginInfo
`group` : | the keyfile group to extract information from
`filename` : | A path to the file containing the plugin info
`error` : | A location for a GError or `NULL`
Returns : | `TRUE` if the data was loaded successfully

### ethos_plugin_info_load_from_key_file ()

    gboolean            ethos_plugin_info_load_from_key_file
                                                            (EthosPluginInfo *plugin_info,
                                                             const gchar *group,
                                                             GKeyFile *key_file,
                                                             GError **error);

Loads the plugin information from `key_file`. The information is loaded from the group named `group` within the keyfile. Therfore, if `group` where "Sample Plugin" then the keyfile should have a group header such as "[Sample Plugin]" within it.

Upon failure, `error` is set and `FALSE` is returned.

`plugin_info` : | An EthosPluginInfo
`group` : | the name of the group to load
`key_file` : | A GKeyFile
`error` : | A location for a GError or `NULL`
Returns : | `TRUE` on success

### ethos_plugin_info_load_from_data ()

    gboolean            ethos_plugin_info_load_from_data    (EthosPluginInfo *plugin_info,
                                                             const gchar *group,
                                                             const gchar *data,
                                                             gsize length,
                                                             GError **error);

Loads the plugin information from a buffer of information. The data should be in GKeyFile format.

`plugin_info` : | A EthosPluginInfo
`group` : | the group to load information from
`data` : | a buffer of data
`length` : | length of buffer to use
`error` : | A location for a GError or `NULL`
Returns : | `TRUE` on success. `error` is set on failure.

### ethos_plugin_info_get_id ()

    const gchar*        ethos_plugin_info_get_id            (EthosPluginInfo *plugin_info);

Retreives the unique id of the plugin.

`plugin_info` : | An EthosPluginInfo
Returns : | The unique id of the plugin which should not be modified or freed.

### ethos_plugin_info_set_id ()

    void                ethos_plugin_info_set_id            (EthosPluginInfo *plugin_info,
                                                             const gchar *id);

Sets the id of the plugin. This is typically taking from the filename of the description file.

`plugin_info` : | An EthosPluginInfo
`id` : | the id of the plugin

### ethos_plugin_info_get_filename ()

    const gchar*        ethos_plugin_info_get_filename      (EthosPluginInfo *plugin_info);

Retreives the filename that was used to load the `plugin_info`.

`plugin_info` : | An EthosPluginInfo
Returns : | A string or `NULL`

### ethos_plugin_info_set_filename ()

    void                ethos_plugin_info_set_filename      (EthosPluginInfo *plugin_info,
                                                             const gchar *filename);

Sets the filename used to load the plugin-info.

`plugin_info` : | An EthosPluginInfo
`filename` : | The filename

### ethos_plugin_info_get_name ()

    const gchar*        ethos_plugin_info_get_name          (EthosPluginInfo *plugin_info);

Retrieves the name of the plugin.

`plugin_info` : | An EthosPluginInfo
Returns : | The name of the plugin. This value should not be freed or modified.

### ethos_plugin_info_get_module ()

    const gchar*        ethos_plugin_info_get_module        (EthosPluginInfo *plugin_info);

Retreives the module that implements an EthosPlugin.

`plugin_info` : | An EthosPluginInfo
Returns : | The module of the plugin. This value should not be modified or freed.

### ethos_plugin_info_get_loader ()

    const gchar*        ethos_plugin_info_get_loader        (EthosPluginInfo *plugin_info);

Retrieves the name of the EthosPluginLoader that should load the plugin.

`plugin_info` : | An EthosPluginInfo
Returns : | The loader to use to load the plugin. This value should not be modified or freed.

### ethos_plugin_info_get_authors ()

    gchar**             ethos_plugin_info_get_authors       (EthosPluginInfo *plugin_info);

Retreives the authors of the plugin.

`plugin_info` : | An EthosPluginInfo
Returns : | A `NULL` terminated array of strings that contain the authors. This value should not be modified or freed.

### ethos_plugin_info_get_description ()

    const gchar*        ethos_plugin_info_get_description   (EthosPluginInfo *plugin_info);

Retrieves the description of the plugin

`plugin_info` : | An EthosPluginInfo
Returns : | A string containing the description. The string should not be modified or freed.

### ethos_plugin_info_get_copyright ()

    const gchar*        ethos_plugin_info_get_copyright     (EthosPluginInfo *plugin_info);

Retrieves the copyright of the plugin

`plugin_info` : | An EthosPluginInfo
Returns : | A string containing the copyright. The string should not be modified or freed.

### ethos_plugin_info_get_website ()

    const gchar*        ethos_plugin_info_get_website       (EthosPluginInfo *plugin_info);

Retrieves the website url of the plugin

`plugin_info` : | An EthosPluginInfo
Returns : | A string containing the website. The string should not be modified or freed.

### ethos_plugin_info_get_version ()

    const gchar*        ethos_plugin_info_get_version       (EthosPluginInfo *plugin_info);

Retrieves the version of the plugin

`plugin_info` : | An EthosPluginInfo
Returns : | the version of the plugin

### ethos_plugin_info_get_dependencies ()

    const gchar*        ethos_plugin_info_get_dependencies  (EthosPluginInfo *plugin_info);

Retrieves the list of dependencies as a string. The string is a set of checks that must pass before the plugin can be loaded.

Such as:

"network >= 0.1 xmpp"

Would require the network plugin 0.1 or greater and any version of the xmpp plugin.

`plugin_info` : | An EthosPluginInfo
Returns : | A string containing the dependencies or `NULL`.

### ethos_plugin_info_get_icon_name ()

    const gchar*        ethos_plugin_info_get_icon_name     (EthosPluginInfo *plugin_info);

Retrieves the icon field for the EthosPluginInfo

`plugin_info` : | An EthosPluginInfo
Returns : | A string containing the icon name or `NULL`. This value should not be modified or freed.

### ethos_plugin_info_get_active ()

    gboolean            ethos_plugin_info_get_active        (EthosPluginInfo *plugin_info);

Retrieves whether or not the plugin is currently activated.

`plugin_info` : | An EthosPluginInfo
Returns : | `TRUE` if the plugin is currently active

### ethos_plugin_info_set_active ()

    void                ethos_plugin_info_set_active        (EthosPluginInfo *plugin_info,
                                                             gboolean active);

Set the active status of the EthosPluginInfo. This is useful so that gui front-ends can keep track if the plugin is currently in use.

`plugin_info` : | An EthosPluginInfo
`active` : | if the EthosPluginInfo is active

### ethos_plugin_info_get_iage ()

    guint               ethos_plugin_info_get_iage          (EthosPluginInfo *plugin_info);

Retreives the interface age that the plugin conforms to.

`plugin_info` : | An EthosPluginInfo
Returns : | a guint containing the age.

### ethos_plugin_info_has_errors ()

    gboolean            ethos_plugin_info_has_errors        (EthosPluginInfo *plugin_info);

Checks whether or not the plugin has had any errors.

`plugin_info` : | An EthosPluginInfo
Returns : | `TRUE` if the plugin had an error loading.

### ethos_plugin_info_get_errors ()

    GList*              ethos_plugin_info_get_errors        (EthosPluginInfo *plugin_info);

Retrieves a list of errors that occurred while trying to load the plugin. If no errors have occurred, NULL is returned. The list is a copy however the GErrors contained are not. You should free the list with `g_list_free()`.

`plugin_info` : | An EthosPluginInfo
Returns : | A GList containing GErrors that should be freed with `g_list_free()`.

## Property Details

### The `"active"` property

      "active"                   gboolean              : Read

Whether or not the plugin is currently loaded.

Default value: FALSE

### The `"authors"` property

      "authors"                  GStrv*                : Read

The list of authors that have contributed to the plugin.

### The `"copyright"` property

      "copyright"                gchar*                : Read

The copyright the plugin is released under such as "GPL-2".

Default value: NULL

### The `"dependencies"` property

      "dependencies"             gchar*                : Read

Dependencies that must be loaded for the plugin to load. See `ethos_plugin_info_get_dependencies()`.

Default value: NULL

### The `"description"` property

      "description"              gchar*                : Read

A short description of the plugin.

Default value: NULL

### The `"filename"` property

      "filename"                 gchar*                : Read / Write

The filename that was used to load the plugin.

Default value: NULL

### The `"icon-name"` property

      "icon-name"                gchar*                : Read

The name of the icon to display in the manager widgets.

Default value: NULL

### The `"id"` property

      "id"                       gchar*                : Read / Write

Unique identifier for the plugin.

Default value: NULL

### The `"loader"` property

      "loader"                   gchar*                : Read

The name of the EthosPluginLoader that should be used to load the plugin.

Default value: NULL

### The `"module"` property

      "module"                   gchar*                : Read

The name of the module that should be used to load the plugin.

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read

The name of the plugin.

Default value: NULL

### The `"version"` property

      "version"                  gchar*                : Read

The version of the plugin. See `ethos_plugin_info_get_version()`.

Default value: NULL

### The `"website"` property

      "website"                  gchar*                : Read

The website to find more information on the plugin.

Default value: NULL

## Signal Details

### The `"loaded"` signal

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

Signal emitted when a new plugin is loaded.

`plugin_info` : | An EthosPluginInfo
`user_data` : | user data set when the signal handler was connected.

### The `"unloaded"` signal

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

Signal emitted when the plugin is unloaded.

`plugin_info` : | An EthosPluginInfo
`user_data` : | user data set when the signal handler was connected.