## gwymoduleloader gwymoduleloader — Basic module loader interface |

## Functions

#define | GWY_MODULE_QUERY()
gboolean | (*GwyModuleRegisterFunc) ()
GwyModuleInfo * | (*GwyModuleQueryFunc) ()
GQuark | gwy_module_error_quark ()
void | gwy_module_register_modules ()
const GwyModuleInfo * | gwy_module_lookup ()
const gchar * | gwy_module_get_filename ()
GSList * | gwy_module_get_functions ()
void | gwy_module_foreach ()
const GwyModuleInfo * | gwy_module_register_module ()

## Types and Values

#define | GWY_MODULE_ABI_VERSION
enum | GwyModuleError
struct | GwyModuleInfo

## Includes

    #include <libgwymodule/gwymodule.h>

## Description

## Functions

### GWY_MODULE_QUERY()

    #define             GWY_MODULE_QUERY(mod_info)

The module query must be 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).

If you write a module in C++ note the module query must have C linkage. This is achieved by marking it `extern "C"`:

    1
    2
    3
    extern "C" {
    GWY_MODULE_QUERY(module_info)
    }

This has to be done manually in versions up to 2.24; since version 2.25 `GWY_MODULE_QUERY()` includes `extern "C"` automatically if it is compiled using a C++ compiler.

#### Parameters

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

### GwyModuleRegisterFunc ()

    gboolean
    (*GwyModuleRegisterFunc) (void);

Module registration function type.

It actually runs particular featrue registration functions, like `gwy_file_func_register()` and `gwy_process_func_register()`.

#### 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.

#### Parameters

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

### gwy_module_lookup ()

    const GwyModuleInfo *
    gwy_module_lookup (const gchar *name);

Returns information about one module.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

### GWY_MODULE_ABI_VERSION

    #define GWY_MODULE_ABI_VERSION 2

Gwyddion module ABI version.

To be filled as `abi_version` in GwyModuleInfo.

### enum GwyModuleError

Type of module loading and registration error.

#### Members

GWY_MODULE_ERROR_NAME | Module has an invalid name. It is recommended that module names are valid C identifiers, possibly with dashes instead of underscores, but only really broken names are rejected. |
GWY_MODULE_ERROR_DUPLICATE | A module of the same name has already been registered. |
GWY_MODULE_ERROR_OPEN | Calling `g_module_open()` on the module failed. |
GWY_MODULE_ERROR_QUERY | Module does not contain any query function. |
GWY_MODULE_ERROR_ABI | Module has different ABI version than expected/supported; or required info field are missing. |
GWY_MODULE_ERROR_INFO | Module query function provided `NULL` info. |
GWY_MODULE_ERROR_REGISTER | The registration function returned `FALSE`; or the module did not register any function. |

### struct GwyModuleInfo

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

Module information returned by `GWY_MODULE_QUERY()`.

#### Members

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). |