PeasPluginInfo

## PeasPluginInfo PeasPluginInfo — Information about a plugin. |

## Synopsis

                        PeasPluginInfo;
    enum                PeasPluginInfoError;
    gboolean            peas_plugin_info_is_loaded          (const PeasPluginInfo *info);
    gboolean            peas_plugin_info_is_available       (const PeasPluginInfo *info,
                                                             GError **error);
    gboolean            peas_plugin_info_is_builtin         (const PeasPluginInfo *info);
    gboolean            peas_plugin_info_is_hidden          (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_module_name    (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_module_dir     (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_data_dir       (const PeasPluginInfo *info);
    GSettings *         peas_plugin_info_get_settings       (const PeasPluginInfo *info,
                                                             const gchar *schema_id);
    const gchar **      peas_plugin_info_get_dependencies   (const PeasPluginInfo *info);
    gboolean            peas_plugin_info_has_dependency     (const PeasPluginInfo *info,
                                                             const gchar *module_name);
    const gchar *       peas_plugin_info_get_name           (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_description    (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_icon_name      (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_help_uri       (const PeasPluginInfo *info);
    const gchar **      peas_plugin_info_get_authors        (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_website        (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_copyright      (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_version        (const PeasPluginInfo *info);
    const gchar *       peas_plugin_info_get_external_data  (const PeasPluginInfo *info,
                                                             const gchar *key);

## Object Hierarchy

      GBoxed
       +----PeasPluginInfo

## Description

A PeasPluginInfo contains all the information available about a plugin.

All this information comes from the related plugin info file, whose file extension is ".plugin". Here is an example of such a plugin file, in the GKeyFile format:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    [Plugin]
    Module=helloworld
    Name=Hello World
    Description=Displays "Hello World"
    Authors=Steve Frécinaux <code@istique.net>
    Copyright=Copyright © 2009-10 Steve Frécinaux
    Website=http://live.gnome.org/Libpeas
    Help=http://library.gnome.org/devel/libpeas/unstable/
    IAge=2

## Details

### PeasPluginInfo

    typedef struct _PeasPluginInfo PeasPluginInfo;

The PeasPluginInfo structure contains only private data and should only be accessed using the provided API.

### enum PeasPluginInfoError

    typedef enum {
      PEAS_PLUGIN_INFO_ERROR_LOADING_FAILED,
      PEAS_PLUGIN_INFO_ERROR_LOADER_NOT_FOUND,
      PEAS_PLUGIN_INFO_ERROR_DEP_NOT_FOUND,
      PEAS_PLUGIN_INFO_ERROR_DEP_LOADING_FAILED
    } PeasPluginInfoError;

These identify the various errors that can occur while loading a plugin.

`PEAS_PLUGIN_INFO_ERROR_LOADING_FAILED` | The plugin failed to load.
`PEAS_PLUGIN_INFO_ERROR_LOADER_NOT_FOUND` | The plugin's loader was not found.
`PEAS_PLUGIN_INFO_ERROR_DEP_NOT_FOUND` | A dependency of the plugin was not found.
`PEAS_PLUGIN_INFO_ERROR_DEP_LOADING_FAILED` | A dependency of the plugin failed to load.

### peas_plugin_info_is_loaded ()

    gboolean            peas_plugin_info_is_loaded          (const PeasPluginInfo *info);

Check if the plugin is loaded.

`info` : | A PeasPluginInfo.
Returns : | `TRUE` if the plugin is loaded.

### peas_plugin_info_is_available ()

    gboolean            peas_plugin_info_is_available       (const PeasPluginInfo *info,
                                                             GError **error);

Check if the plugin is available.

A plugin is marked as not available when there is no loader available to load it, or when there has been an error when trying to load it previously. If not available then `error` will be set.

`info` : | A PeasPluginInfo.
`error` : | A GError.
Returns : | `TRUE` if the plugin is available.

### peas_plugin_info_is_builtin ()

    gboolean            peas_plugin_info_is_builtin         (const PeasPluginInfo *info);

Check if the plugin is a builtin plugin.

A builtin plugin is a plugin which cannot be enabled or disabled by the user through a plugin manager (like PeasGtkPluginManager). Loading or unloading such plugins is the responsibility of the application alone. Most applications will usually load those plugins immediately after the initialization of the PeasEngine.

The relevant key in the plugin info file is "Builtin".

`info` : | A PeasPluginInfo.
Returns : | `TRUE` if the plugin is a builtin plugin, `FALSE` if not.

### peas_plugin_info_is_hidden ()

    gboolean            peas_plugin_info_is_hidden          (const PeasPluginInfo *info);

Check if the plugin is a hidden plugin.

A hidden plugin is a plugin which cannot be seen by a user through a plugin manager (like PeasGtkPluginManager). Loading and unloading such plugins is the responsibility of the application alone or through plugins that depend on them.

The relevant key in the plugin info file is "Hidden".

`info` : | A PeasPluginInfo.
Returns : | `TRUE` if the plugin is a hidden plugin, `FALSE` if not.

### peas_plugin_info_get_module_name ()

    const gchar *       peas_plugin_info_get_module_name    (const PeasPluginInfo *info);

Gets the module name.

The module name will be used to find the actual plugin. The way this value will be used depends on the loader (i.e. on the language) of the plugin. This value is also used to uniquely identify a particular plugin.

The relevant key in the plugin info file is "Module".

`info` : | A PeasPluginInfo.
Returns : | the module name.

### peas_plugin_info_get_module_dir ()

    const gchar *       peas_plugin_info_get_module_dir     (const PeasPluginInfo *info);

Gets the module directory.

The module directory is the directory where the plugin file was found. This is not a value from the GKeyFile, but rather a value provided by the PeasEngine.

`info` : | A PeasPluginInfo.
Returns : | the module directory.

### peas_plugin_info_get_data_dir ()

    const gchar *       peas_plugin_info_get_data_dir       (const PeasPluginInfo *info);

Gets the data dir of the plugin.

The module data directory is the directory where a plugin should find its runtime data. This is not a value read from the GKeyFile, but rather a value provided by the PeasEngine, depending on where the plugin file was found.

`info` : | A PeasPluginInfo.
Returns : | the plugin's data dir.

### peas_plugin_info_get_settings ()

    GSettings *         peas_plugin_info_get_settings       (const PeasPluginInfo *info,
                                                             const gchar *schema_id);

Creates a new GSettings for the given `schema_id` and if gschemas.compiled is not in the module directory an attempt will be made to create it.

`info` : | A PeasPluginInfo.
`schema_id` : | The schema id. [allow-none]
Returns : | a new GSettings, or `NULL`. [transfer full]

### peas_plugin_info_get_dependencies ()

    const gchar **      peas_plugin_info_get_dependencies   (const PeasPluginInfo *info);

Gets the dependencies of the plugin.

The PeasEngine will always ensure that the dependencies of a plugin are loaded when the said plugin is loaded. It means that dependencies are loaded before the plugin, and unloaded after it. Circular dependencies of plugins lead to undefined loading order.

The relevant key in the plugin info file is "Depends".

`info` : | A PeasPluginInfo.
Returns : | the plugin's dependencies. [transfer none]

### peas_plugin_info_has_dependency ()

    gboolean            peas_plugin_info_has_dependency     (const PeasPluginInfo *info,
                                                             const gchar *module_name);

Check if the plugin depends on another plugin.

`info` : | A PeasPluginInfo.
`module_name` : | The name of the plugin to check.
Returns : | whether the plugin depends on the plugin `module_name`.

### peas_plugin_info_get_name ()

    const gchar *       peas_plugin_info_get_name           (const PeasPluginInfo *info);

Gets the name of the plugin.

The name of a plugin should be a nice short string to be presented in UIs.

The relevant key in the plugin info file is "Name".

`info` : | A PeasPluginInfo.
Returns : | the plugin's name.

### peas_plugin_info_get_description ()

    const gchar *       peas_plugin_info_get_description    (const PeasPluginInfo *info);

Gets the description of the plugin.

The description of the plugin should be a string presenting the purpose of the plugin. It will typically be presented in a plugin's about box.

The relevant key in the plugin info file is "Description".

`info` : | A PeasPluginInfo.
Returns : | the plugin's description.

### peas_plugin_info_get_icon_name ()

    const gchar *       peas_plugin_info_get_icon_name      (const PeasPluginInfo *info);

Gets the icon name of the plugin.

The icon of the plugin will be presented in the plugin manager UI. If no icon is specified, the default green puzzle icon will be used.

The relevant key in the plugin info file is "Icon".

`info` : | A PeasPluginInfo.
Returns : | the plugin's icon name.

### peas_plugin_info_get_help_uri ()

    const gchar *       peas_plugin_info_get_help_uri       (const PeasPluginInfo *info);

Gets the help URI of the plugin.

The Help URI of a plugin will typically be presented by the plugin manager as a "Help" button linking to the URI. It can either be a HTTP URL on some website or a ghelp: URI if a Gnome help page is available for the plugin.

The relevant key in the plugin info file is "Help". Other platform-specific keys exist for platform-specific help files. Those are "Help-GNOME", "Help-Windows" and "Help-MacOS-X".

`info` : | A PeasPluginInfo.
Returns : | the plugin's help URI.

### peas_plugin_info_get_authors ()

    const gchar **      peas_plugin_info_get_authors        (const PeasPluginInfo *info);

Gets a `NULL`-terminated array of strings with the authors of the plugin.

The relevant key in the plugin info file is "Authors".

`info` : | A PeasPluginInfo.
Returns : | the plugin's author list. [transfer none][array zero-terminated=1]

### peas_plugin_info_get_website ()

    const gchar *       peas_plugin_info_get_website        (const PeasPluginInfo *info);

Gets the website of the plugin.

The relevant key in the plugin info file is "Website".

`info` : | A PeasPluginInfo.
Returns : | the plugin's associated website.

### peas_plugin_info_get_copyright ()

    const gchar *       peas_plugin_info_get_copyright      (const PeasPluginInfo *info);

Gets the copyright of the plugin.

The relevant key in the plugin info file is "Copyright".

`info` : | A PeasPluginInfo.
Returns : | the plugin's copyright information.

### peas_plugin_info_get_version ()

    const gchar *       peas_plugin_info_get_version        (const PeasPluginInfo *info);

Gets the version of the plugin.

The relevant key in the plugin info file is "Version".

`info` : | A PeasPluginInfo.
Returns : | the plugin's version.

### peas_plugin_info_get_external_data ()

    const gchar *       peas_plugin_info_get_external_data  (const PeasPluginInfo *info,
                                                             const gchar *key);

Gets external data specified for the plugin.

External data is specified in the plugin info file prefixed with X-. For example, if a key/value pair X-Peas=1 is specified in the key file, you can use "Peas" for `key` to retrieve the value "1".

Note: that you can omit the X- prefix when retrieving the value, but not when specifying the value in the file.

`info` : | A PeasPluginInfo.
`key` : | The key to lookup.
Returns : | the external data, or `NULL` if the external data could not be found.