http://cronosII.sourceforge.net
While you read this manual and code your plugin, I recommend you open the sample plugin which comes in the source distribution of Cronos II. ( In the directory /plugins/sample/sample.c) Then you can see how plugins are structured. When you code your own plugin you should code with that same structure to avoid confusing errors.
A plugin is a compiled module which can be loaded dynamically by a program, in this case, Cronos II.
The term Dynamic Loading means that the module can be loaded on the fly, while the program is running.Plugins are designed to fulfill an specific task, like decoding incoming messages and encoding outgoing messages (GnuPG plugin), randomly selecting a signature, or any other thing you can think of, you can even make changes to the UI (User Interface) of Cronos II.
Plugins development might sound like a really difficult thing if this is your first attempt to do such a thing. Actually, the development of plugins for Cronos II is a really simple task thanks to the API Cronos II brings to you.
Cronos II Plugins Development is done through signals. (Note that these signals are not the same as the Unix system signals, and are not implemented using them, although the terminology is almost identical.) When an event occurs, such as the downloading of a new message, the appropriate signal will be emitted by Cronos II.When a signal is emitted, all functions connected to that signal are called passing specific signal parameters.
Plugins which don't connect to any signal are useless plugins, so you should always connect your plugin to a signal.
The way to connect to a signal is by calling a function in the initialization function of the module, which will always be module_init.
c2_dynamic_module_signal_connect (const char *module_name, C2DynamicModuleSignal signal,C2DynamicModuleSignalFunc func);Where the first argument is the name of the module, the second argument is the type of signal (View Signal List). The third argument is a function of type C2DynamicModuleSignalFunc which will be called when this signal is emitted.
The functions of type C2DynamicModuleSignalFunc look like this:
void function (void *arg1, void *arg2, void *arg3, void *arg4, void *arg4, void *arg5);Note that they may also ignore any or all of the arg* variables, ie:
void function (void *arg1, void *arg2);When you connect to a signal, some data, of an specific type will be passed to the function you connected (called a function callback), thus you might want to specify the type of variable in the function definition.
Ie. You might want to use a function callback of type:
void function (const char *message, const char *username);for a signal that passes such arguments instead of:
void function (void *arg1, void *arg2);This works just like GTK+ or GNOME.
Note that when you pass the third argument to the function c2_dynamic_module_signal_connect you should always use the macro C2_DYNAMIC_MODULE_SIGNAL_FUNC (function) to ensure the cast is correctly done.
Connected signals can be disconnected, once you don't want to use them any more or when the module is required to clean up
(View module_cleanup).The way to do this is calling the function:
void c2_dynamic_module_signal_disconnect (const char *module_name, C2DynamicModuleSignal signal);Where the first argument is the name of the module and the second is the type of signal.
Callback functions are called out of the main thread, outside of where the gtk_main function is being executed. Thus if you want to do draw something in the user interface (ie. a window) you must call two functions.gdk_threads_enter () is called before doing anything that would update the interface, like calling gtk_widget_show or something like that. gdk_threads_leave () is called after updating the interface.If you want to do a callback that draws a simple window you should code something like this:
void graphic_function (void) { GtkWidget *window; window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_window_set_title (GTK_WINDOW (window), "Sample window"); gdk_threads_enter (); gtk_widget_show (window); gdk_threads_leave (); }
C2_DYNAMIC_MODULE_CHECK_NEW_SESSION (int length) @length: Number of accounts to be checked.Definition: This signal is emitted every time a checking session is about to start or some account is added to the checking queue while active.
C2_DYNAMIC_MODULE_CHECK_NEW_ACCOUNT (Account *account) @account: Account to be checked.Definition: This signal is emitted every time checking of an account is about to start.
C2_DYNAMIC_MODULE_MESSAGE_DOWNLOAD_POP (Message *message) @message: Message downloaded.Definition: This signal is emitted every time a message is downloaded from a POP account.
C2_DYNAMIC_MODULE_MESSAGE_DOWNLOAD_SPOOL (Message *message) @message: Message downloaded.Definition: This signal is emitted every time a message is downloaded from a SPOOL account.
C2_DYNAMIC_MODULE_COMPOSER_SEND (Message *message) @message: Message to be sent.Definition: This signal is emitted every time a message is about to be sent.
C2_DYNAMIC_MODULE_COMPOSER_INSERT_SIGNATURE (char **signature) @*signature: Signature to be added.Definition: This signal is emitted every time a signature is going to be appended to a message in the composer window.
C2_DYNAMIC_MODULE_WINDOW_FOCUS (const char *type) @type: Name of window. (ie. main, composer, checker)Definition: This signal is emitted every time a window gains focus.
C2_DYNAMIC_MODULE_MESSAGE_OPEN (Message *message, const char *type) @message: Message to be opened. @type: Type of opening. (preview, composer, message)Definition: This signal is emitted every time a message is opened in someway to take some action on it. Note: This signal is emitted from the gdk thread, so be careful how you use it!
The function module_init is the first function called of any module. The structure of this function is as follows:
char *module_init (int major_version, int minor_version, int micro_version, C2DynamicModule *module);This function should return NULL on success or an string describing why the module hasn't been loaded.
This function should do the following things in this order (plus anything else you require):
The first argument of this function is major version number of the Cronos II running version, the second argument is the minor version and the third argument is the micro version.
The major version is the first number of the version (0.2.0).
The minor version is the second number of the version (0.2.0).
The micro version is the third number of the version (0.2.0).
The fourth argument is a pointer to an allocated C2DynamicModule object that this function should fill with valid information.
- Check if the Cronos II version is better or equal to the version you requite. This is done because your module might need some special API provided by some version. For example, plugins are supported since version 0.2.0, therefore you should always require, at least, this version.
- Check if this plugin is already loaded using the function c2_dynamic_module_find.
- Set up module (some module information):
- name: Name of the plugin (eg. "GnuPG"),
- version: Version of the plugin (eg. "0.1"),
- author: Name and email of the author of the plugin (e.g. "Pablo Fernández Navarro <cronosII@users.sourcefroge.net>"),
- url: URL where this plugin can be downloaded (e.g. "http://cronosII.sourceforge.net"),
- description: A description of what this plugin does (ie. "Decodes incoming encoded messages and encodes outgoing messages"),
- configure: Pointer to a function that will be called when the user wants to configure the plugin (View Configure). If you don't want your users to configure the plugin you should set it to NULL,
- configfile: This should be set to the return of the function c2_dynamic_module_get_config_file.
- Load the configuration (if your plugin uses configuration).
- Connect the signals (View Connecting)
The function module_cleanup is the function called when the user wants to unload the plugin or when Cronos II is exiting.The typography of this function is as follows:
void module_cleanup (C2DynamicModule *module);The first and unique argument is a pointer to the C2DynamicModule containing the plugin information.
This function should do the following things and anything else you require:
- Disconnect all connected signals.
You may want the user to be able to configure the plugin.eg. The sample plugin does a simple task: when a mail from a specific address arrives the user is notified with a simple gnome_ok_dialog.
The part that we will talk about in this section is the from a specific address.
How can you know which address should be waiting for notifying the user? Simple, with a configuration window.You might noticed that the Preferences dialog, in the section of "Plug-Ins" is the one that handles the stuff related to the plugins. There's a button named "Configure".
When that button is pressed the function pointed by module->configure is called unless you set module->configure to NULL.
Cronos II gives you a tool for correctly installing the plugin, you should really use it.This tool is called cronosII-config, it gets installed when you install Cronos II. By using it you will know where to install the plugin (`cronosII-config --datadir`/plugins) and what version is currently installed.
You should always keep in mind that Cronos II is designed for GNOME, thus you should always try to design interfaces with the look & feel of GNOME, using gnome_stock_button and similar functions ( the libgnomeui library).
Cronos II hasn't many signals (yet). If you need to work with a signal that is currently not emitted (like a signal when a message is deleted), you should just mail me asking for it at cronosII@users.sourceforge.net. I will add it for you as soon as I can do it.
(Please, include in your request how your plugin will use it.)
Cronos II has an extended API which is getting larger and larger with each new version. Having a list of the API is a hard job which would delay the release of versions too much.At the time of programming your plugins you're probably going to need to use this API, unless your plugin does a really simple task, such as showing "Hello world" each time your module is loaded and "Ronnie was playing in the field" each time the module is unloaded.
The best way for you to understand the functions in Cronos II is to read the source files. Most functions are documented in the .c files. Anyway, functions in Cronos II are very intuitive and self describing.
If you have any doubt about what a function, or a family of functions does, or how you should work with them you could check some functions that use them (you can locate them using the GNU grep tool) or you can mail me at cronosII@users.sourceforge.net.
Once you finished writing the first version of your plugin, please, send the URL for it (if you made a home page for it) or send me the tarball by mail to cronosII@users.sourceforge.net.