Module loader: Gwyddion Application Library Reference Manual

## Module loader Module loader — Basic module loader interface |

## Functions

void | (*GwyProcessFunc) ()
#define | GWY_MODULE_QUERY()
#define | GWY_MODULE_QUERY2()
gboolean | (*GwyModuleRegisterFunc) ()
GwyModuleInfo * | (*GwyModuleQueryFunc) ()
const GwyModuleRecord * | (*GwyModuleBundleRegisterFunc) ()
GQuark | gwy_module_error_quark ()
gint | gwy_module_register_modules ()
const GwyModuleInfo * | gwy_module_lookup ()
const gchar * | gwy_module_get_filename ()
GSList * | gwy_module_get_functions ()
void | gwy_module_foreach ()
void | gwy_module_failure_foreach ()
const GwyModuleInfo * | gwy_module_register_module ()
void | gwy_module_disable_registration ()
void | gwy_module_enable_registration ()
gboolean | gwy_module_is_enabled ()

## Types and Values

enum | GwyRunModeFlags
#define | GWY_MODULE_ABI_VERSION
#define | GWY_MODULE_BUNDLE_FLAG
#define | GWY_MODULE_ERROR
enum | GwyModuleError
struct | GwyModuleRecord
struct | GwyModuleInfo
| GwyModuleFailureInfo

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

## Functions

### GwyProcessFunc()

    void
    (*GwyProcessFunc) (GwyFile *data,
                       GwyRunModeFlags run);

The type of data processing function.

This is a temporary type. Module calling will change substantially.

#### Parameters

data | The data container to operate on. |
run | Run mode. |

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

### GWY_MODULE_QUERY2()

    #define             GWY_MODULE_QUERY2(mod_info,mod_name)

The module query must be the ONLY exported symbol from a module.

See `GWY_MODULE_QUERY` for discussion.

This macro is intended for modules that can be bundled together to one big shared library for time and space optimization. This mostly makes sense only for modules included in Gwyddion itself as it contains hundreds of modules.

However, it safe to use in third party modules because if modules are not bundled the macro behaves exactly as `GWY_MODULE_QUERY` and the `mod_name` argument is just ignored. The macro expansion differs only when `GWY_MODULE_BUNDLING` is defined when including the "gwymoduleloader.h" header.

The module name `mod_name` is given as a C identifier, not a string. It must be identical to the file name of the module if it was installed standalone, with extension removed and with non-identifier characters converted to underscores. For instance module implemented in "nt-mdt.c" and installed as "nt-mdt.so" or "nt-mdt.dll" (or with other extensions, depending on the operating system) must pass `nt_mdt`. If it does not match the file name, linking will fail with a confusing message when bundling is enabled.

#### Parameters

mod_info | The GwyModuleInfo structure to return as module info. |
mod_name | Module name, given as C identifier corresponding to file name withough extension. |

### GwyModuleRegisterFunc()

    gboolean
    (*GwyModuleRegisterFunc) (void);

Module registration function type.

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

If the module has a complex initialisation it may be safer to simply not register any function but return `TRUE` even if it fails to set up itself correctly. The module feature unregistration is somewhat crude and, generally, unregisteration may lead to disaster when shared library unloading has unexpected side effects.

#### Returns

Whether the registration succeeded. When it returns `FALSE`, the module and its features are unregistered.

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

### GwyModuleBundleRegisterFunc()

    const GwyModuleRecord *
    (*GwyModuleBundleRegisterFunc) (void);

Module bundle query function type.

It returns an array of module records for all modules in the bundle, terminated by {`NULL`, `NULL`}.

### 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()

    gint
    gwy_module_register_modules (const gchar *path,
                                 GwyErrorList **error_list);

Registers all modules in a directory, with one level of recursion.

It can be called several times on different directories. Registering the same module multiple times is an error. The recursion does not follow symlinks to directories. If you registred modules in non-standard directories, it is not recommended to deviate from the standard one level deep subdirectory scheme with modules organised by type.

An error summary is reported. For specific registration errors, register modules individually with `gwy_module_register_module()`.

If you need to prevent specific modules from loading use `gwy_module_disable_registration()` beforehand.

#### Parameters

path | A module directory name. |
error_list | Location to store the errors occuring, `NULL` to ignore. |

#### Returns

A positive number (the number of successfully registered modules) modules were found and all were registered successfully. A negative number if there were any errors. Zero if `path` is valid but no modules were found there.

### 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_failure_foreach()

    void
    gwy_module_failure_foreach (GFunc function,
                                gpointer data);

Runs `function` for each module that failed to register.

It passes the failure info (GwyModuleFailureInfo) as the data argument. It should be modified.

#### Parameters

function | A GFunc run for each module registration failure. |
data | User data. |

### gwy_module_register_module()

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

Loads a single module.

This function also works with bundles. The returned module info is for the bundle and thus not of much use.

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

### gwy_module_disable_registration()

    void
    gwy_module_disable_registration (const gchar *name);

Prevents the registration of a module of given name.

This function blocks future module registration using `gwy_module_register_modules()`. Already loaded modules are unaffected. The low-level module loading function `gwy_module_register_module()` always attempts to load the module, even if blocked.

#### Parameters

name | A module name. |

### gwy_module_enable_registration()

    void
    gwy_module_enable_registration (const gchar *name);

Unblocks the registration of a module of given name.

This function influences future module registration. Already loaded modules are unaffected.

#### Parameters

name | A module name. |

### gwy_module_is_enabled()

    gboolean
    gwy_module_is_enabled (const gchar *name);

Reports whether the registration of a module is enabled.

If the registration of module `name` was prevented using `gwy_module_disable_registration()` and not subsequently re-enabled using `gwy_module_enabled_registration()` this function returns `FALSE`.

The reported values only represents the current state of blocking. A module `name` could have been loaded when it was not blocked.

#### Parameters

name | A module name. |

#### Returns

`TRUE` if module `name` can be registered; `FALSE` when it is blocked from registration.

## Types and Values

### enum GwyRunModeFlags

Module function run mode flags.

The values are used as flags when a function declares the supported modes. However, when a function is executed, it is always in a specific mode. It can simply use equality tests to find out the mode (as opposed to testing which flags are set).

Note `GWY_RUN_NONINTERACTIVE` is only possible for file functions, processing functions do not have a truly non-interactive interface yet and therefore they should not claim they support it. The closest match for process functions is `GWY_RUN_IMMEDIATE` .

#### Members

GWY_RUN_NONE | None. |
GWY_RUN_NONINTERACTIVE | The function is run non-interactively, it must not present any GUI nor touch application state. |
GWY_RUN_INTERACTIVE | The function presents a modal user interfaces where parameters can be adjusted, it returns after finishing all operations. |
GWY_RUN_IMMEDIATE | Function is run immediately and uses parameter values stored in the settings to reproduce previous run. It can however present GUI error messages or display progress, create new windows, etc. |

### GWY_MODULE_ABI_VERSION

    #define GWY_MODULE_ABI_VERSION 3

Gwyddion module ABI version.

To be filled as `abi_version` in GwyModuleInfo.

### GWY_MODULE_BUNDLE_FLAG

    #define GWY_MODULE_BUNDLE_FLAG 256u

Value to bitwise combine with `GWY_MODULE_ABI_VERSION` to indicate a bundle.

### GWY_MODULE_ERROR

    #define GWY_MODULE_ERROR gwy_module_error_quark()

Error domain for module loading.

Errors in this domain will be from the GwyModuleError enumeration. See GError for information on error domains.

### 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. |
GWY_MODULE_ERROR_NESTING | Nested module bundle found. (Since 2.49) |

### struct GwyModuleRecord

    struct GwyModuleRecord {
        GwyModuleQueryFunc query;
        const gchar *name;
    };

Module record returned by bundle query function.

#### Members

GwyModuleQueryFunc `query`; | Module query function. |
const gchar *`name`; | Module name (base file name without extensions). |

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

### GwyModuleFailureInfo

    typedef struct {
        const gchar *filename;
        const gchar *modname;
        const gchar *err_message;
        gint err_domain;
        gint err_code;
    } GwyModuleFailureInfo;

Information about a failed module registration.

#### Members

const gchar *`filename`; | Name of the file the module was loaded from. |
const gchar *`modname`; | Module name (can be `NULL` and contain odd bytes). |
const gchar *`err_message`; | Error message from the failed module registration. |
gint `err_domain`; | GError domain from the failed module registration. |
gint `err_code`; | GError code from the failed module registration. |