Plug-in API

An event-driven C API for extending the hub.

Each plug-in registers a set of callback functions for handling events when it is loaded. Plug-ins can also register user commands that show up in the hub for users to interact with — see the example plug-in for how. The full API is defined in the source code.

Creating a plug-in

A plug-in must implement at least two functions, called when loading and unloading it:

/**
 * 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*);

The configuration string is passed verbatim from the plug-in configuration file.

struct plugin_handle

The plugin_handle struct is passed to every callback. It exposes hub functions (hub) for the plug-in to use, and a data pointer (ptr) to anchor memory the plug-in allocates.

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;
};

plugin_register() is the only function allowed to modify most of the struct, conveniently done with the PLUGIN_INITIALIZE macro:

int plugin_register(struct plugin_handle* handle, const char* config)
{
    PLUGIN_INITIALIZE(handle, "test", "1.0", "A simple test plug-in");
    return 0;
}

Registering callbacks

Set the relevant function pointer in the funcs member of plugin_handle. For example, a plug-in that prints 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 struct plugin_funcs.