modapi.txt

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 <mkd64/common.h>:

- 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 <mkd64/imodule.h>

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.