Plugin development
From NNTPGrab
As of NNTPGrab 0.6.0 (SVN revision 1339) the program is fully plugin based. This makes it very easy to add new functionality to the program. New functionality can be added in the form of seperate plugins. This documentation describes the steps needed to create a plugin suitable for NNTPGrab.
Contents |
Lifecycle of a plugin
All plugins need to implement a number of functions. These functions need to be exported before the plugin can be loaded from the NNTPGrab Core:
void nntpgrab_plugin_initialize(NGPlugin *plugin_data) ngboolean nntpgrab_plugin_load(NGPlugin *plugin_data, char **errmsg) ngboolean nntpgrab_plugin_can_unload(NGPlugin *plugin_data, char **reason) void nntpgrab_plugin_unload(NGPlugin *plugin_data) void nntpgrab_plugin_destroy(NGPlugin *plugin_data) int nntpgrab_plugin_get_version(void)
The NGPlugin structure
The NGPlugin structure is defined in the file plugins/nntpgrab_plugin.h. Plugins must include this file. The NGPlugin structure looks like this:
typedef struct _ng_plugin { GObject parent; NGPluginCoreData *core_data; gpointer priv; } NGPlugin;
This structure contains 3 fields. The first field is GObject parent. This is used internally by GLib/GObject and must not be touched by plugins
The second field is NGPluginCoreData *core_data. This is a pointer to a structure containing internal plugin information which is maintained by the NNTPGrab Core. This structure also must not be touched by plugins
The third field is gpointer priv. Plugins can put any kind of data in this field
nntpgrab_plugin_initialize
On startup of NNTPGrab, the program searches in the plugin folder for all the available plugins. This is done by searching files which implement all the functions which were listed above.
To retrieve information about the plugin, this function is called automatically. Must of the time, this function is implemented like this:
void nntpgrab_plugin_initialize(NGPlugin *plugin_data) { ng_plugin_set_name(plugin_data, "Example"); ng_plugin_set_version(plugin_data, "1.0"); ng_plugin_set_author(plugin_data, "Erik van Pienbroek"); ng_plugin_set_url(plugin_data, "https://www.nntpgrab.nl"); ng_plugin_set_description(plugin_data, "Example plugin which prints a message in the console every time a file is added"); }
If the plugin want to offer new functionality (functions) to the NNTPGrab Core or other plugins then the function ng_plugin_register_function() can be used here If the plugin wants to use functionality (functions) from other plugins, then this can be indicated by using the function ng_plugin_set_required_function()
This is also the only place where the functions ng_plugin_register_function() and ng_plugin_set_required_function() can be used
nntpgrab_plugin_load
This function will be called by the NNTPGrab Core when the plugin needs to be loaded and get ready to used. The function ng_plugin_connect_event() can be used here to connect to events.
If wanted, the plugin_data->priv field can be initialized here to something useful
nntpgrab_plugin_can_unload
NNTPGrab frontends can call this function to find out whether the plugin is performing a task at the moment. If this is the case, the parameter char **reason can be set to a small comment about the active task and the value FALSE can be returned. If the plugin isn't doing anything at the moment, the value TRUE can be returned
nntpgrab_plugin_unload
Whenever a plugin needs to be unloaded (because of program shutdown or on the user's request) this function will be called. It's basically the reverse of the nntpgrab_plugin_load function. If the plugin_data->priv field was set, then it can be cleared here It isn't necessary to unregister any event connections (done by ng_plugin_connect_event()) as that'll be automatically done by the NNTPGrab Core
nntpgrab_plugin_destroy
On program shutdown, this function will be automatically called. Most plugins don't need to add any implementation to this function
nntpgrab_plugin_get_version
The implementation of this function must be the same across all plugins. All that needs to happen is a return NNTPGRAB_PLUGIN_API_VERSION;. With this information, the NNTPGrab Core can find out if the plugin is using the same API version of the NNTPGrab Core is expecting. When an API mismatch is detected, the plugin will be ignored
Executing functions of other plugins
Whenever a plugin want to use functionality from another plugin, a special function has to be used: ng_plugin_call()
This function expects a variable number of arguments. The first parameters (which are always required) are a pointer to an instance of the NGPlugin structure (which is used across all plugin functions) and a function name. Depending on the function which needs to be executed, zero or more additional arguments are needed.
If the function which needs to be executed has a return value, then it needs to be added as the last parameter to the ng_plugin_call() call.
To help the NNTPGrab Core in dependency resolving, any external function which will be used by the plugin needs to be registered with the ng_plugin_set_required_function() function in the nntpgrab_plugin_initialize() function
Every function expects a different set of parameters. To find out what the right expected parameters are see the API documentation section
Connecting to events of other plugins
Plugins can emit events whenever something has occured. Other plugins can connect to these event by using the ng_plugin_connect_event() function This function expects a pointer to an instance of the NGPlugin structure (which is used across all plugin functions), an event name and the name of the function which needs to be invoked whenever the event occurs.
Every event has a different set of arguments. To find out what the right expected parameters are see the API documentation section
API documentation
For a list of functions which NNTPGrab plugins can use to communicate with other plugins, see https://www.nntpgrab.nl/api/nntpgrab__plugin_8h.html
At the moment there isn't a complete list of all the functions and events which the NNTPGrab plugin export. To find out this information you have to look in the marshall.list files which are bundled along with several plugins:
Config plugin Schedular plugin NNTP plugin Decoder plugin PAR2 plugin Unpack plugin
Example plugin
For a simple example plugin, see the file plugins/example/example.c. This is a very basic plugin which waits for an event called schedular_task_added to occur. Whenever the event occurs, some parameters belonging to that specific event are printed in the console
