Next: , Previous: Plugin mechanism implementation, Up: Plugins

10.2 Rules for writing plugins

The plugin interface must be properly initialized and cleaned up by functions plugin_init and plugin_finish. A plugin is loaded via the function plugin_load and (possibly) unloaded by plugin_unload.

Every valid VRR plugin must contain the function u32 plugin_start(void). Make sure the prototype is exactly this. plugin_start is called immediately after the successful plugin loading and its purpose is to perform initialization routines as well as plugin function registering. The plugin flags are described in the return value. If you wish your plugin to be unloadable, make sure you set the flag PLUGIN_UNLOADABLE.

Every exported plugin function must of prototype union plugin_arg func(union plugin_arg *arg) or void func(union plugin_arg *arg). The exported plugin functions are registered into the interface via the function plugin_function_register.

This is an example (taken from plugin/hell.c):

     u32 plugin_start(void)
       plugin_function_register("tsunami", NULL, PLUGIN_T_VOID,
                                2, PLUGIN_T_REAL, PLUGIN_T_REAL);
       plugin_function_register("hilbert_curve", NULL, PLUGIN_T_VOID,
                                2, PLUGIN_T_OBJ_TLO, PLUGIN_T_INT);
       plugin_function_register("random_pastes", NULL, PLUGIN_T_VOID,
                                2, PLUGIN_T_OBJ_TLO, PLUGIN_T_INT);
       plugin_function_register("show_horizontal_points", NULL, PLUGIN_T_VOID,
                                1, PLUGIN_T_OBJ_TLO);
       plugin_function_register("test_solve_y", NULL, PLUGIN_T_VOID,
                                2, PLUGIN_T_OBJ_TLO, PLUGIN_T_REAL);
       plugin_function_register("plus", "adds two integer numbers", PLUGIN_T_INT,
                                2, PLUGIN_T_INT, PLUGIN_T_INT);
       return 0;

Similarly, when unloading an (unloadable) plugin, the function plugin_stop is executed, if present in the plugin.

In general, it is possible (as the plugin is a solid part of VRR after loading) to change every single variable and execute every function VRR has for its internal purposes, but doing that is discouraged. Try to write the plugins in the cleanest possible way.