GIMP Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gimpmodule

## Name

gimpmodule -- Common definitions for creating a pluggable GIMP module.

## Synopsis

    enum        GimpModuleStatus;
    struct      GimpModuleInfo;
    GimpModuleStatus (*GimpModuleInitFunc)      (GimpModuleInfo **module_info);
    void        (*GimpModuleCompletedCB)        (gpointer completed_data);
    void        (*GimpModuleUnloadFunc)         (gpointer shutdown_data,
                                                 GimpModuleCompletedCB completed_cb,
                                                 gpointer completed_data);

## Description

Common definitions for creating a pluggable GIMP module.

## Details

### enum GimpModuleStatus

    typedef enum
    {
      GIMP_MODULE_OK,
      GIMP_MODULE_UNLOAD
    } GimpModuleStatus;

### struct GimpModuleInfo

    struct GimpModuleInfo
    {
      gpointer     shutdown_data;

      const gchar *purpose;
      const gchar *author;
      const gchar *version;
      const gchar *copyright;
      const gchar *date;
    };

### GimpModuleInitFunc ()

    GimpModuleStatus (*GimpModuleInitFunc)      (GimpModuleInfo **module_info);

GIMP modules should G_MODULE_EXPORT a function named "module_init" of this type.

The "module_init" function is called by the GIMP at startup, and should return either GIMP_MODULE_OK if it sucessfully initialised or GIMP_MODULE_UNLOAD if the module failed to hook whatever functions it wanted. GIMP_MODULE_UNLOAD causes the module to be closed, so the module must not have registered any internal functions or given out pointers to its data to anyone.

If the module returns GIMP_MODULE_OK, it should also return a GimpModuleInfo structure describing itself.

`module_info` : | Returns the GimpModuleInfo desribing the module.
Returns : | A GimpModuleStatus value indicating success.

### GimpModuleCompletedCB ()

    void        (*GimpModuleCompletedCB)        (gpointer completed_data);

The type of the `completed_cb` passed to the "module_unload" function (see below).

`completed_data` : | Must be the `completed_data` pointer provided by the "module_unload" function.

### GimpModuleUnloadFunc ()

    void        (*GimpModuleUnloadFunc)         (gpointer shutdown_data,
                                                 GimpModuleCompletedCB completed_cb,
                                                 gpointer completed_data);

If GIMP modules want to allow themselves to be unloaded, they should G_MODULE_EXPORT a function named "module_unload" of this type.

GIMP calls the "module_unload" unload request function to ask a module to prepare itself to be unloaded. It is called with the value of `shutdown_data` supplied in the GimpModuleInfo struct. The module should ensure that none of its code or data are being used, and then call the supplied `completed_cb` callback function with the `completed_data` provided. Typically the shutdown request function will queue de-registration activities then return. Only when the de-registration has finished should the `completed_cb` be invoked.

`shutdown_data` : | The `shutdown_data` supplied in the GimpModuleInfo struct.
`completed_cb` : | The function to call after successful unload.
`completed_data` : | Has to be passed to the `completed_cb`.

## See Also

GModule

<<< Previous Page | Home | Up | Next Page >>>
GIMP Module Header Files | gimpcolordisplay