Chapter 2. Technical

Table of Contents

Requirements
int ebplugin_init(void)
int ebplugin_message(int msgcode, void *msgdata1, void *msgdata2)
void ebplugin_deinit(void)
Plugin API
Guidelines & Hints
Converting Old Plugins

Requirements

eboxy plugins are shared libraries that are linked to libeboxyplugin.a and implement all of the following C style functions:

int ebplugin_init(void)

Put code in this function to initialise your plugin. Other than your own initialisation code (if any) you should call setPluginInfo() somewhere in here with the full name of your plugin and a version string. When you're done, return an exit status: 0 for success, or any other value to indicate failure (which will result in the plugin not being loaded).

int ebplugin_message(int msgcode, void *msgdata1, void *msgdata2)

This function will be called when certain other events occur. Currently this exists just to let your plugin know when the page or file is changed.

This function may be extended for other events in future. For now, msgcode can be one of the following events (see pluginconstants.h for constants):

Message constantDescription
PLMSG_PLUGINSTARTissued when your plugin has been loaded
PLMSG_BEFOREPAGECHANGEissued before the current page is to be changed
PLMSG_AFTERPAGECHANGEissued after a new page has been displayed
PLMSG_BEFOREFILELOADissued before a new XML file is to be loaded
PLMSG_AFTERFILELOADissued after a new XML file has been loaded

The return value is currently unused, but you should return 0 for compatibility with future usage. Also, any msgcode values your plugin does not understand (ie, that do not match any of the current PLMSG_ constants, or at least none of them that you're interested in) should be ignored silently by your code.

void ebplugin_deinit(void)

In this function, put any code you need to clean up after your plugin. eboxy will call this before it unloads the plugin. You must not call any plugin API functions from this procedure.

Plugins must define all three of these functions, and must be linked to libeboxyplugin.a (the eboxy plugin client library), or they will not be loaded. Beyond these, you may define any other functions and use any libraries you need (however, please read the guidelines section).

The plugin system has an built-in version checking mechanism. eboxy can read the version of libeboxyplugin.a that your plugin was linked with, and so can determine if your plugin is too new or too old to work with it. Future versions of eboxy will be designed with as much backwards compatibility as possible.