gwymoduleloader

gwymoduleloader — Basic module loader interface

Functions

Types and Values

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