## gwymoduleloader

gwymoduleloader — Basic module loader interface

## Synopsis

    #include <libgwymodule/gwymodule.h>

    #define             GWY_MODULE_ABI_VERSION
    #define             GWY_MODULE_QUERY                    (mod_info)
    #define             GWY_MODULE_ERROR
    enum                GwyModuleError;
                        GwyModuleInfo;
    gboolean            (*GwyModuleRegisterFunc)            (void);
    GwyModuleInfo*      (*GwyModuleQueryFunc)               (void);
    GQuark              gwy_module_error_quark              (void);
    void                gwy_module_register_modules         (const gchar **paths);
    const GwyModuleInfo* gwy_module_lookup                  (const gchar *name);
    const gchar*        gwy_module_get_filename             (const gchar *name);
    GSList*             gwy_module_get_functions            (const gchar *name);
    void                gwy_module_foreach                  (GHFunc function,
                                                             gpointer data);
    const GwyModuleInfo* gwy_module_register_module         (const gchar *name,
                                                             GError **error);

## Description

## Details

### GWY_MODULE_ABI_VERSION

    #define GWY_MODULE_ABI_VERSION 2

Gwyddion module ABI version.

To be filled as `abi_version` in GwyModuleInfo.

### GWY_MODULE_QUERY()

    #define             GWY_MODULE_QUERY(mod_info)

The declaration of module info query (the ONLY exported symbol from a module).

This macro does The Right Thing necessary to export module info in a way Gwyddion understands it. Put GWY_MODULE_QUERY with the module info (GwyModuleInfo) of your module as its argument on a line (with NO semicolon after).

`mod_info` : | The GwyModuleInfo structure to return as module info.

### GWY_MODULE_ERROR

    #define GWY_MODULE_ERROR gwy_module_error_quark()

### enum GwyModuleError

    typedef enum {
        GWY_MODULE_ERROR_NAME,
        GWY_MODULE_ERROR_DUPLICATE,
        GWY_MODULE_ERROR_OPEN,
        GWY_MODULE_ERROR_QUERY,
        GWY_MODULE_ERROR_ABI,
        GWY_MODULE_ERROR_INFO,
        GWY_MODULE_ERROR_REGISTER
    } GwyModuleError;

### GwyModuleInfo

    typedef struct {
        guint32 abi_version;
        GwyModuleRegisterFunc register_func;
        const gchar *blurb;
        const gchar *author;
        const gchar *version;
        const gchar *copyright;
        const gchar *date;
    } GwyModuleInfo;

Module information returned by `GWY_MODULE_QUERY()`.

guint32 `abi_version`; | Gwyddion module ABI version, should be always GWY_MODULE_ABI_VERSION.
GwyModuleRegisterFunc `register_func`; | Module registration function (the function run by Gwyddion module system, actually registering particular module features).
const gchar *`blurb`; | Some module description.
const gchar *`author`; | Module author(s).
const gchar *`version`; | Module version.
const gchar *`copyright`; | Who has copyright on this module.
const gchar *`date`; | Date (year).

### GwyModuleRegisterFunc ()

    gboolean            (*GwyModuleRegisterFunc)            (void);

Module registration function type.

It actually runs particular featrue registration functions, like `gwy_module_register_file_func()` and `gwy_module_register_process_func()`.

Returns : | Whether the registration succeeded. When it returns `FALSE`, the module and its features are unloaded (FIXME: maybe. Currenly only module is unloaded, features are NOT unregistered, this can lead to all kinds of disasters).

### GwyModuleQueryFunc ()

    GwyModuleInfo*      (*GwyModuleQueryFunc)               (void);

Module query function type.

The module query function should be simply declared as GWY_MODULE_QUERY(mod_info), where mod_info is module info struct for the module.

Returns : | The module info struct.

### gwy_module_error_quark ()

    GQuark              gwy_module_error_quark              (void);

Returns error domain for module loading.

See and use `GWY_MODULE_ERROR`.

Returns : | The error domain.

### gwy_module_register_modules ()

    void                gwy_module_register_modules         (const gchar **paths);

Registers all modules in given directories.

It can be called several times (on different directories). No errors are reported, register modules individually with `gwy_module_register_module()` to get registration errors.

`paths` : | A `NULL`-terminated list of directory names.

### gwy_module_lookup ()

    const GwyModuleInfo* gwy_module_lookup                  (const gchar *name);

Returns information about one module.

`name` : | A module name.
Returns : | The module info, of `NULL` if not found. It must be considered constant and never modified or freed.

### gwy_module_get_filename ()

    const gchar*        gwy_module_get_filename             (const gchar *name);

Returns full file name of a module.

`name` : | A module name.
Returns : | Module file name as a string that must be modified or freed.

### gwy_module_get_functions ()

    GSList*             gwy_module_get_functions            (const gchar *name);

Returns list of names of functions a module implements.

`name` : | A module name.
Returns : | List of module function names, as a GSList that is owned by module loader and must not be modified or freed.

### gwy_module_foreach ()

    void                gwy_module_foreach                  (GHFunc function,
                                                             gpointer data);

Runs `function` on each registered module.

It passes module name as the key and pointer to module info (GwyModuleInfo) as the value. Neither should be modified.

`function` : | A GHFunc run for each module.
`data` : | User data.

### gwy_module_register_module ()

    const GwyModuleInfo* gwy_module_register_module         (const gchar *name,
                                                             GError **error);

Loads a single module.

`name` : | Module file name to load, including full path and extension.
`error` : | Location to store error, or `NULL` to ignore them. Errors from GwyModuleError domain can occur.
Returns : | Module info on success, `NULL` on failure.