gwymoduleloader

gwymoduleloader — Basic module loader interface

Synopsis

#include <libgwymodule/gwymodule.h>

#define             GWY_MODULE_ABI_VERSION
#define             GWY_MODULE_QUERY                    (mod_info)
enum                GwyModuleError;
gboolean            (*GwyModuleRegisterFunc)            (void);
GwyModuleInfo *     (*GwyModuleQueryFunc)               (void);
struct              GwyModuleInfo;
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 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.

mod_info :

 The GwyModuleInfo structure to return as module info.

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;

Type of module loading and registration error.

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.

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.

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

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

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.
Generated by GTK-Doc V1.19