mkd64 module API ---------------- To start creating your own module, use "Makefile" and "module.c" from examples/modules. These files are found in the source tree, the mkd64 SDK, and are typically installed to $(prefix)/share/doc/mkd64. Every module must contain the macro call MKD64_MODULE("modulename"). This defines the mkd64ApiVersion() and id() calls for the module. It may create other private symbols, e.g. static variables containing the return values for these calls, that SHALL NOT BE USED by module implementations. The API version consists of a MAJOR and MINOR number. The MINOR number is increased whenever there are additions to the API that don't break compatibility. When compatibility is broken by an API change, the MAJOR number is increased and the MINOR number restarts at 0. The mkd64 module loader will consider any module with the same API version or an older but compatible one. 1. static module interface mkd64 tries to load all modules in its directory at startup. To be able to load, each module must export the following function, using the SOEXPORT macro from : - IModule *instance(void) Create an instance of the module. Instance should be structs with a first member of type IModule (the dynamic module interface), so they are convertible to and from IModule *. The following functions MAY be exported: - const char **depends(void) A pointer to a null-terminated string array containing the ids of modules that must be activated for the current module to work correctly. mkd64 makes sure they are loaded before loading the current module. - const char **conflicts(void) A pointer to a null-terminated string array containing the ids of modules that conflict with the current module. If any of them is loaded, the current module will not load. Otherwise, they are marked so they cannot be loaded later. - const char *help(void) Should return a help string for the module that contains a list of all global options understood by this module - const char *helpFile(void) Should return a help string describing all file options understood by this module - const char *versionInfo(void) Should return a string containing version information about the module and a short description. It's probably a good idea to include some build information, too (e.g. using the mkd64 buildid tool) 2. dynamic module interface The module instance created by instance() must contain an IModule struct as its first member. The function pointers in this struct are called automatically by mkd64 when an event occurs. If an event is not needed by the module, the pointer can be left NULL. The following two members of IModule MUST BE IMPLEMENTED by every module instance: - const char *(*id)(void) This should return the module id, so the instance could be identified at runtime. Just let it point to id() generated by MKD64_MODULE macro. - void (*delete)(IModule *) Delete the given module instance. This should free all memory allocated by instance(). For the other implementable methods, see the header 3. mkd64 public API Every module can call mkd64 methods and functions. You find the public functions in include/mkd64/. Most of the time, it should be possible to figure out what they are doing just from their names and arguments. Nevertheless, those headers will eventuelly get commented. 4. modules written in C++ The mkd64 public API is designed to be directly usable from C++ code. You don't need to put any `extern "C"' declarations yourself. But think twice before actually implementing a module in C++: Do it in plain C if you don't really have a compelling need for C++, e.g. a dependency on a C++ library. C++ modules will never be included in the main mkd64 tree, because they add a lot of complexity and mkd64 should not depend on anything other than a C Compiler (C99-conforming or MSVC). 5. bigger examples See the implementations of the included modules (in the modules directory of the source tree) for examples how to create mkd64 modules actually doing something.