![]() |
![]() |
![]() |
Gwyddion Module Library Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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
);
#define GWY_MODULE_ABI_VERSION 2
Gwyddion module ABI version.
To be filled as abi_version
in GwyModuleInfo.
#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.
|
The GwyModuleInfo structure to return as module info. |
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;
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). |
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 { 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 |
Gwyddion module ABI version, should be always GWY_MODULE_ABI_VERSION. |
GwyModuleRegisterFunc |
Module registration function (the function run by Gwyddion module system, actually registering particular module features). |
const gchar * |
Some module description. |
const gchar * |
Module author(s). |
const gchar * |
Module version. |
const gchar * |
Who has copyright on this module. |
const gchar * |
Date (year). |
GQuark gwy_module_error_quark (void
);
Returns error domain for module loading.
See and use GWY_MODULE_ERROR
.
Returns : |
The error domain. |
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.
|
A NULL -terminated list of directory names. |
const GwyModuleInfo * gwy_module_lookup (const gchar *name
);
Returns information about one module.
|
A module name. |
Returns : |
The module info, of NULL if not found. It must be considered
constant and never modified or freed. |
const gchar * gwy_module_get_filename (const gchar *name
);
Returns full file name of a module.
|
A module name. |
Returns : |
Module file name as a string that must be modified or freed. |
GSList * gwy_module_get_functions (const gchar *name
);
Returns list of names of functions a module implements.
|
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. |
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.
|
A GHFunc run for each module. |
|
User data. |
const GwyModuleInfo * gwy_module_register_module (const gchar *name
,GError **error
);
Loads a single module.
|
Module file name to load, including full path and extension. |
|
Location to store error, or NULL to ignore them. Errors from
GwyModuleError domain can occur. |
Returns : |
Module info on success, NULL on failure. |