## GimpModule

GimpModule — A GTypeModule subclass which implements module loading using GModule.

## Synopsis

                GimpModule;
                GimpModuleInfo;
    enum        GimpModuleState;
    const GimpModuleInfo* (*GimpModuleQueryFunc)
                                                (GTypeModule *module);
    gboolean    (*GimpModuleRegisterFunc)       (GTypeModule *module);
    #define     GIMP_MODULE_ABI_VERSION
    #define     GIMP_MODULE_PARAM_SERIALIZE
    GimpModule* gimp_module_new                 (const gchar *filename,
                                                 gboolean load_inhibit,
                                                 gboolean verbose);
    void        gimp_module_modified            (GimpModule *module);
    gboolean    gimp_module_query_module        (GimpModule *module);
    void        gimp_module_set_load_inhibit    (GimpModule *module,
                                                 gboolean load_inhibit);
    const gchar* gimp_module_state_name         (GimpModuleState state);
    GType       gimp_module_register_enum       (GTypeModule *module,
                                                 const gchar *name,
                                                 const GEnumValue *const_static_values);
    GimpModuleInfo* gimp_module_info_new        (guint32 abi_version,
                                                 const gchar *purpose,
                                                 const gchar *author,
                                                 const gchar *version,
                                                 const gchar *copyright,
                                                 const gchar *date);
    GimpModuleInfo* gimp_module_info_copy       (const GimpModuleInfo *info);
    void        gimp_module_info_free           (GimpModuleInfo *info);

## Object Hierarchy

      GObject
       +----GTypeModule
             +----GimpModule

## Implemented Interfaces

GimpModule implements GTypePlugin.

## Signal Prototypes

    "modified"  void        user_function      (GimpModule *gimpmodule,
                                                gpointer user_data);

## Description

A GTypeModule subclass which implements module loading using GModule.

## Details

### GimpModule

    typedef struct {
      gchar           *filename;     /* path to the module                       */
      gboolean         verbose;      /* verbose error reporting                  */
      GimpModuleState  state;        /* what's happened to the module            */
      gboolean         on_disk;      /* TRUE if file still exists                */
      gboolean         load_inhibit; /* user requests not to load at boot time   */

      /* stuff from now on may be NULL depending on the state the module is in   */
      GimpModuleInfo  *info;         /* returned values from module_query        */
      gchar           *last_module_error;
    } GimpModule;

GimpModule is a generic mechanism to dynamically load modules into the GIMP. It is a GTypeModule subclass, implementing module loading using GModule. GimpModule does not know which functionality is implemented by the modules, it just provides a framework to get arbitrary GType implementations loaded from disk.

### GimpModuleInfo

    typedef struct {
      guint32  abi_version;
      gchar   *purpose;
      gchar   *author;
      gchar   *version;
      gchar   *copyright;
      gchar   *date;
    } GimpModuleInfo;

This structure contains information about a loadable module.

guint32 `abi_version`; | The GIMP_MODULE_ABI_VERSION the module was compiled against.
gchar *`purpose`; | The module's general purpose.
gchar *`author`; | The module's author.
gchar *`version`; | The module's version.
gchar *`copyright`; | The module's copyright.
gchar *`date`; | The module's release date.

### enum GimpModuleState

    typedef enum
    {
      GIMP_MODULE_STATE_ERROR,       /* missing gimp_module_register function
                                      * or other error
                                      */
      GIMP_MODULE_STATE_LOADED,      /* an instance of a type implemented by
                                      * this module is allocated
                                      */
      GIMP_MODULE_STATE_LOAD_FAILED, /* gimp_module_register returned FALSE
                                      */
      GIMP_MODULE_STATE_NOT_LOADED   /* there are no instances allocated of
                                      * types implemented by this module
                                      */
    } GimpModuleState;

The possible states a GimpModule can be in.

`GIMP_MODULE_STATE_ERROR` | Missing `gimp_module_register()` function or other error.
`GIMP_MODULE_STATE_LOADED` | An instance of a type implemented by this module is allocated.
`GIMP_MODULE_STATE_LOAD_FAILED` | `gimp_module_register()` returned FALSE.
`GIMP_MODULE_STATE_NOT_LOADED` | There are no instances allocated of types implemented by this module.

### GimpModuleQueryFunc ()

    const GimpModuleInfo* (*GimpModuleQueryFunc)
                                                (GTypeModule *module);

The signature of the query function a loadable GIMP module must implement. In the module, the function must be called `gimp_module_query()`.

GimpModule will copy the returned GimpModuleInfo struct, so the module doesn't need to keep these values around (however in most cases the module will just return a pointer to a constant structure).

`module` : | The GimpModule responsible for this loadable module.
Returns : | The GimpModuleInfo struct describing the module.

### GimpModuleRegisterFunc ()

    gboolean    (*GimpModuleRegisterFunc)       (GTypeModule *module);

The signature of the register function a loadable GIMP module must implement. In the module, the function must be called `gimp_module_register()`.

When this function is called, the module should register all the types it implements with the passed `module`.

`module` : | The GimpModule responsible for this loadable module.
Returns : | TRUE on success, FALSE otherwise.

### GIMP_MODULE_ABI_VERSION

    #define GIMP_MODULE_ABI_VERSION 0x0004

The version of the module system's ABI. Modules put this value into GimpModuleInfo's `abi_version` field so the code loading the modules can check if it was compiled against the same module ABI the modules are compiled against.

### GIMP_MODULE_PARAM_SERIALIZE

    #define GIMP_MODULE_PARAM_SERIALIZE (1 << (0 + G_PARAM_USER_SHIFT))

### gimp_module_new ()

    GimpModule* gimp_module_new                 (const gchar *filename,
                                                 gboolean load_inhibit,
                                                 gboolean verbose);

Creates a new GimpModule instance.

`filename` : | The filename of a loadable module.
`load_inhibit` : | Pass `TRUE` to exclude this module from auto-loading.
`verbose` : | Pass `TRUE` to enable debugging output.
Returns : | The new GimpModule object.

### gimp_module_modified ()

    void        gimp_module_modified            (GimpModule *module);

Emits the "modified" signal. Call it whenever you have modified the module manually (which you shouldn't do).

`module` : | A GimpModule.

### gimp_module_query_module ()

    gboolean    gimp_module_query_module        (GimpModule *module);

Queries the module without actually registering any of the types it may implement. After successful query, the `info` field of the GimpModule struct will be available for further inspection.

`module` : | A GimpModule.
Returns : | `TRUE` on success.

### gimp_module_set_load_inhibit ()

    void        gimp_module_set_load_inhibit    (GimpModule *module,
                                                 gboolean load_inhibit);

Sets the `load_inhibit` property if the module. Emits "modified".

`module` : | A GimpModule.
`load_inhibit` : | Pass `TRUE` to exclude this module from auto-loading.

### gimp_module_state_name ()

    const gchar* gimp_module_state_name         (GimpModuleState state);

Returns the translated textual representation of a GimpModuleState. The returned string must not be freed.

`state` : | A GimpModuleState.
Returns : | The `state`'s name.

### gimp_module_register_enum ()

    GType       gimp_module_register_enum       (GTypeModule *module,
                                                 const gchar *name,
                                                 const GEnumValue *const_static_values);

Registers an enum similar to `g_enum_register_static()` but for modules. This function should actually live in GLib but since there's no such API, it is provided here.

`module` : |
`name` : |
`const_static_values` : |
Returns : | a new enum GType

### gimp_module_info_new ()

    GimpModuleInfo* gimp_module_info_new        (guint32 abi_version,
                                                 const gchar *purpose,
                                                 const gchar *author,
                                                 const gchar *version,
                                                 const gchar *copyright,
                                                 const gchar *date);

Creates a newly allocated GimpModuleInfo struct.

`abi_version` : | The GIMP_MODULE_ABI_VERSION the module was compiled against.
`purpose` : | The module's general purpose.
`author` : | The module's author.
`version` : | The module's version.
`copyright` : | The module's copyright.
`date` : | The module's release date.
Returns : | The new GimpModuleInfo struct.

### gimp_module_info_copy ()

    GimpModuleInfo* gimp_module_info_copy       (const GimpModuleInfo *info);

Copies a GimpModuleInfo struct.

`info` : | The GimpModuleInfo struct to copy.
Returns : | The new copy.

### gimp_module_info_free ()

    void        gimp_module_info_free           (GimpModuleInfo *info);

Frees the passed GimpModuleInfo.

`info` : | The GimpModuleInfo struct to free

## Signals

### The "modified" signal

    void        user_function                  (GimpModule *gimpmodule,
                                                gpointer user_data);

`gimpmodule` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

GModule

GTypeModule