Plug-in API introduction
The plug-in API is an event-driven C API.
Each plugin registers a set of callback functions for handling events when loaded.
The plugins can register user commands that show up in the hub that users can interact with. See the example plugin for how to do that.
The plugin API is defined in the source code at Github.
Creating plug-ins
A plug-in needs to implement at least two functions that are called when loading and unloading the plug-in. These are defined as:
/**
* Implemented by the plugin.
*
* @param handle[out] Sets all information by the plugin
* @param config A configuration string
* @return 0 on success, -1 on error.
*/
int plugin_register(struct plugin_handle* handle, const char* config);
/**
* @return 0 on success, -1 on error.
*/
int plugin_unregister(struct plugin_handle*);
struct plugin_handle
The plugin_handle struct is sent as a parameter to all plugin event callbacks and provides a mechanism for
providing hub functions (hub) to be used by the plug-in, and also a data pointer (ptr) which can be used to anchor memory allocated by the plug-in.
struct plugin_handle
{
struct uhub_plugin* handle;
const char* name;
const char* version;
const char* description;
void* ptr;
const char* error_msg;
size_t plugin_api_version;
size_t plugin_funcs_size;
struct plugin_funcs funcs;
struct plugin_hub_funcs hub;
};
The plugin_register() is the only one that is allowed to modify most parts of the plugin_handle struct.
This is conveniently done with the PLUGIN_INITIALIZE macro, example:
int plugin_register(struct plugin_handle* handle, const char* config)
{
PLUGIN_INITIALIZE(handle, "test", "1.0", "A simple test plug-in");
return 0;
}
Registering callback events
The plug-in can register callback events by setting relevant function pointer in the funcs member of plugin_handle.
Example of a plug-in printing to the console when users join the hub:
static void event_user_login(struct plugin_handle* plugin, struct plugin_user* user)
{
printf("User \"%s\" logged in.\n", user->nick);
}
int plugin_register(struct plugin_handle* handle, const char* config)
{
PLUGIN_INITIALIZE(handle, "test", "1.0", "A simple test plug-in");
plugin->funcs.on_user_login = event_user_login;
return 0;
}
See the full list of available callbacks in the struct plugin_funcs.