There is a lot of documentation to be written and I haven't done so yet. But, for quick references, I pasted some of the things I already wrote.
Intro
-----
This directory holds the plugins default released with the oculus daemon.
Just type 'make' to build them and then copy them into your oculus plugin
directory (usually /usr/share/oculus).
Some notes for plugin developers
--------------------------------
1. Creating oculus plugins
--------------------------
1.1 Internal structure
The .c file should include plugindata.h, which describes datastructures
for plugins. In the plugin, there should be a static array of 'struct
cmd_table', which holds all supported commands and their handlers. Be
sure to close that array with {NULL, NULL, NULL}. The name of that array must
be plugin_commands.
For example:
struct cmd_table_pu plugin_commands[] = {
{"DATA", "handle_data", "Flurks the booboo."},
{"TIME", "show_time", "Shows the time."},
{NULL, NULL, NULL}
};
The handlers must have the following prototype:
struct reply * handler(const char **cmdline);
cmdline is a create_string_array()-created string array with the entire
commandline cmdline[0] is the command handler cmdline[i], i = 1,2,.. are
the parameters.
All plugins must have a int plugin_initialise(void) function, that
initialises internal data structures for the plugin (or config files, or
whatever you have in your mind that needs initialising). The return value of
that function is 0 for success, or any other value for error.
1.2 API calls
Plugins have all the permissions as normal program code. Some interesting
API calls include:
void oc_exit(int errorcode)
A special exit call, that cleans things up nicely
void oc_writelog(const char *entry, ...)
A printf-style function to write to the oculus log, this can be stdout
or a file, depends on commandline parameters and configfile.
Refer to the oculus daemon code for more information, notably the dynamic
buffer functions (very useful in creating your reply).
1.3 Return value
Command handlers must return a pointer to a struct reply, which is defined
in plugindata.h:
struct reply {
int code;
char *result;
};
The result is a the result of the command and will be send to the client.
When it is set to NULL, it will not be sent. The code can be any of the
following (defined in command.h):
OK All is okay, command was succesfull
HELP Help info printed
WELCOME The welcome string
ERR_UNKNOWN An unknown error occurred
ERR_NOSUPPORT Command (or parameter) is not supported
ERR_NOALLOW Command (or parameter) is not allowed
ERR_FAILED Command failed
WRN_WRONGPARAM Wrong parameters for command
KILL_SERVER Server killed (this WILL kill the server when returned)
QUIT Client disconnect (this WILL close the connection when
returned)
Plugins normally will only return any of the following: OK, ERR_FAILED,
WRN_WRONGPARAM, and less often ERR_NOALLOW or ERR_NOSUPPORT.
Those return values are useful for clients. They are all preceded by their
code and a '+' for success or '-' for error or warning. In that case,
clients can immediately see if the command worked, without parsing entire
command lines.
2. Compiling plugins
--------------------
Plugins are normal shared objects. The simplest way to compile them is the
following:
gcc -shared -o libocp_foobar.so -lc libocp_foobar.c
Add -loculus if you also want to use the oculus API.
All plugin names should start with 'libocp_', otherwise the oculus daemon
will not load it. Renaming plugins after compiling them is no problem.
3. Configuration files
----------------------
There is no generic configuration framework. Use whatever you feel like, but
think about the fact that oculus is compiled against libxml2 and libpcre.
Use them. The get_single_textelement() and get_multiple_textelement() (in
config.c) functions are very useful.