Next
Previous
Contents
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 constant | Description |
PLMSG_PLUGINSTART | issued when your plugin has been loaded |
PLMSG_BEFOREPAGECHANGE | issued before the current page is to be changed |
PLMSG_AFTERPAGECHANGE | issued after a new page has been displayed |
PLMSG_BEFOREFILELOAD | issued before a new XML file is to be loaded |
PLMSG_AFTERFILELOAD | issued 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 determine what version of libeboxyplugin.a 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.
The plugin API documentation has been generated in HTML using Doxygen, and
you can view it
here (in eboxy/docs/pluginapi).
- Don't take too much time responding to messages in
ebplugin_message
- these aren't yet threaded by eboxy so the GUI is effectively "frozen"
while code in your plugin runs. Create your own threads if appropriate.
- Be careful what values you pass to eboxy functions - there is very little
checking code at the moment. Particularly, you should never pass NULL
in place of a
char *
unless it is explicitly allowed.
- If you request objects that don't exist, try to set properties that are
read-only, etc. then an error will be printed on stderr. In this case,
functions that return a
char *
will return NULL, and functions that return
an integer result code will return a non-zero value.
- If your plugin was loaded from the System OnLoad event (or a
<plugin>
element within the
<system>
section) rather than the Page
OnLoad event (or a <plugin>
element within in a
<page>
) then the current page has not been created yet when your plugin receives the
PLMSG_PLUGINSTART message, so you should not try to look for any widgets.
- Do not call any plugin API functions in ebplugin_deinit(). Doing so will
likely result in deadlock. Similarly, you must not do anything that might result
in a plugin message being sent to your plugin during ebplugin_init() (eg.
changing the page) - this will result in deadlock as well. If this causes you a
real problem, please let me know. Note that it is not necessary for you to unregister
objects, event handlers etc. at the time your plugin is deinitialised - this
happens automatically. However, widgets and pages your plugins create (if any)
should be deleted if you don't wish them to stay in existence until eboxy exits.
- Bugs in external libraries that you use can cause odd things to happen
in eboxy. Because plugins execute within eboxy itself, there is nothing eboxy can do to prevent
bad code in a plugin (or libraries a plugin uses) from writing garbage all over its
memory. If you are having trouble with a plugin, it may be worth checking if there is
a bug in any libraries you are using in the plugin. Of course, it could just as likely
be a bug in eboxy. I recommend
Valgrind,
an excellent memory debugger that doesn't even require you to recompile the executable you want
to debug. Note that as Valgrind does not support the fancy instructions available on
newer processors (P4, Athlon) make sure you compile eboxy and SDL without optimising
for a newer architecture if you wish to use Valgrind (use
-march=i386
or i486
).
- Unless you want it to remain in memory until eboxy exits (which may be fine,
depending on what you want to do) you are responsible for unloading your plugin,
or allowing the user of your plugin to ask it to unload (through an object
you have registered). When you're ready to unload, call requestUnload(). Note that
unloading may not happen immediately, since it is scheduled to avoid deadlock and
other nasty situations. However, you should avoid doing anything after calling
requestUnload() (that is, having any statements after it in the same function). Of course,
as previously mentioned, if the plugin is loaded from a
<plugin>
element within in a
<page>
in the XML file it will be unloaded automatically when the page stops being
displayed.
- Document your plugin properly, so that users understand how to use it. At least
provide snippets of XML or script to show how to load and use it, or (even better)
provide an example XML skin that demonstrates the plugin in action.
- Do not under any circumstances open up a service on an untrusted network (eg.
the internet) that allows you to pass script code to the runScript() API function
to be executed, unless you are willing to accept the possibility you may be hacked
by doing so. eboxy's security has not been tested, and the trusted flag of runScript
is only designed to give a small measure of protection. You have been warned!
(If you wish to test eboxy for security, please do so and report any bugs you find).
- Try to make the function names that will be exposed to eboxy unique (those functions
which will be passed to the *DL functions, eg. property get/set functions). C does
not allow functions of the same name, so nasty things will happen if there is a clash
with another plugin. The easiest way to avoid this is by using a unique prefix for all
of the functions that will be exposed. For non-exposed functions, you can use any name
you like as normal.
Next
Previous
Contents