From 0b3cbf57875fd692e4ba0b336fefa4bee1ed00dc Mon Sep 17 00:00:00 2001 From: Simeon Simeonov Date: Mon, 26 Feb 2018 11:23:00 +0100 Subject: Initial commit for sylpheed 3.7.0 --- PLUGIN.txt | 406 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 406 insertions(+) create mode 100644 PLUGIN.txt (limited to 'PLUGIN.txt') diff --git a/PLUGIN.txt b/PLUGIN.txt new file mode 100644 index 0000000..b0d9daf --- /dev/null +++ b/PLUGIN.txt @@ -0,0 +1,406 @@ +Sylpheed Plugin Specification +============================= + +The following is the architecture of plugin system of Sylpheed. + + +----------+ +----------------------+ +-----------+ + | Sylpheed |----| libsylpheed-plugin-0 |--+--| Plug-in A | + +----------+ +----------------------+ | +-----------+ + Sylpheed Plug-in interface | Plug-in DLL + library +--+ + | +------------+ | | +-----------+ + +--------| libsylph-0 |---------+ +--| Plug-in B | + +------------+ +-----------+ + LibSylph mail library + +Sylpheed loads the plug-in DLLs installed in the plug-in directory on +startup. + +Plug-in can only access the functions of Sylpheed through the APIs provided +with libsylpheed-plugin-0 and libsylph-0 library. + +There are two kinds of plug-in API. One is called directly from plug-ins, +another one utilizes the signal mechanism of GObject and calls the callback +functions on specific events. + +The plug-in system is implemented in libsylph/sylmain.[ch] and +src/plugin.[ch]. + + +Plug-in API +=========== + +Functions used by Sylpheed +-------------------------- + +------------------------------------------------------------------------- +void syl_plugin_signal_connect (const gchar *name, GCallback callback, + gpointer data); + +Connects to signals available with SylPlugin object (obtained inside library). +The specification of callback functions that receive signals is similar to +that of normal GObject. +Refer to the signals list for available signals. +------------------------------------------------------------------------- +void syl_plugin_signal_disconnect(gpointer func, gpointer data); + +Disconnects signals connected by syl_plugin_signal_connect(). +------------------------------------------------------------------------- +void syl_plugin_signal_emit(const gchar *name, ...); + +Emits SylPlugin object signals. +------------------------------------------------------------------------- +gint syl_plugin_init_lib (void); + +Initializes the libsylpheed-plugin-0 library. +------------------------------------------------------------------------- +gint syl_plugin_load (const gchar *file); + +Loads plug-in DLL files into memory. +------------------------------------------------------------------------- +gint syl_plugin_load_all (const gchar *dir); + +Loads plug-in DLL files in the specified directory into memory. +------------------------------------------------------------------------- +void syl_plugin_unload_all (void); + +Unloads all loaded plug-ins. +------------------------------------------------------------------------- +GSList *syl_plugin_get_module_list (void); + +Obtains the list of plug-ins loaded into memory. +It returns the list of pointers to GModule struct. +The list is obtained by the library internally, so it must not be freed. +------------------------------------------------------------------------- +SylPluginInfo *syl_plugin_get_info (GModule *module); + +Obtains plug-in information. The information is returned as SylPluginInfo +struct. +------------------------------------------------------------------------- +gboolean syl_plugin_check_version (GModule *module); + +Compares plug-in interface versions and checks if the plug-in is compatible. +Returns TRUE if the version matches, FALSE otherwise. +------------------------------------------------------------------------- +gint syl_plugin_add_symbol (const gchar *name, gpointer sym); + +Registers symbol name and pointer value related to it to the library. +------------------------------------------------------------------------- +gpointer syl_plugin_lookup_symbol (const gchar *name); + +Searches symbol registered by syl_plugin_add_symbol() and returns its +pointer value. +------------------------------------------------------------------------- + + +Functions which must be implemented by plug-ins +----------------------------------------------- + +------------------------------------------------------------------------- +void plugin_load(void) + +Called from Sylpheed on plug-in load. +Do initialization of plug-in etc. here. +------------------------------------------------------------------------- +void plugin_unload(void) + +Called from Sylpheed on plug-in unload. +Do finalization of plug-in etc. here. +------------------------------------------------------------------------- +SylPluginInfo *plugin_info(void) + +Fuction to return struct which stores plug-in information to Sylpheed. +It normally returns pointer to static struct. +------------------------------------------------------------------------- +gint plugin_interface_version(void) + +Function to return plug-in API interface version to Sylpheed. +A plug-in normally returns constant value SYL_PLUGIN_INTERFACE_VERSION. +Sylpheed compares this value with its own value and checks if it is +compatible. Sylpheed's plug-in interface version must be equal to or greater +than the plug-in's plug-in interface verson. If the major versions of the +interface version differ, they are treated as incompatible. + +Ex.1: Sylpheed plug-in interface version: 0x0102 + A plug-in plug-in interface version: 0x0100: OK +Ex.2: Sylpheed plug-in interface version: 0x0102 + A plug-in plug-in interface version: 0x0103: NG +------------------------------------------------------------------------- + + +Functions used by plug-ins +-------------------------- + +Refer to the header file plugin.h for the functions list. + + +Signals list +------------ + +* libsylpheed-plugin-0 + +Call syl_plugin_signal_connect() to use the following signals. + +Example: + syl_plugin_signal_connect("plugin-load", G_CALLBACK(plugin_load_cb), data); + +------------------------------------------------------------------------- +void (* plugin_load) (GObject *obj, GModule *module); + +Emitted on plug-in loading by syl_plugin_load(). +------------------------------------------------------------------------- +void (* plugin_unload) (GObject *obj, GModule *module); + +Emitted on plug-in unloading by syl_plugin_unload_all(). +------------------------------------------------------------------------- +void (* folderview_menu_popup) (GObject *obj, gpointer ifactory); + +Emitted on popup of the context menu of FolderView. +------------------------------------------------------------------------- +void (* summaryview_menu_popup) (GObject *obj, gpointer ifactory); + +Emitted on popup of the context menu of SummaryView. +------------------------------------------------------------------------- +void (* compose_created) (GObject *obj, gpointer compose); + +Emitted on creating 'Compose' message composition window. +------------------------------------------------------------------------- +void (* compose_destroy) (GObject *obj, gpointer compose); + +Emitted just before 'Compose' message composition window is destroyed. +------------------------------------------------------------------------- +void (* textview_menu_popup) (GObject *obj, + GtkMenu *menu, + GtkTextView *textview, + const gchar *uri, + const gchar *selected_text, + MsgInfo *msginfo); + +Emitted on popup of the context menu of TextView. +You can add any menu items to the passed GtkMenu. +The menu object will be created on open and destroyed on close, so menu items +must be added each time. + +menu: context menu object +textview: GtkTextView object +uri: URI string if the menu popups on an URI +selected_text: string if a string is selected on the text view +msginfo: the MsgInfo message object displayed in the text view +------------------------------------------------------------------------- +gboolean (* compose_send) (GObject *obj, + gpointer compose, + gint compose_mode, + gint send_mode, + const gchar *msg_file, + GSList *to_list); + +Emitted on a composed message is being sent. +If FALSE is returned, the message is sent normally. +If TRUE is returned, sending is cancelled. + +compose: the Compose object +compose_mode: ComposeMode enum +send_mode: 0: send immediately 1: queue and send later +msg_file: path to the created message file +to_list: list of recipients +------------------------------------------------------------------------- +void (* messageview_show) (GObject *obj, + gpointer msgview, + MsgInfo *msginfo, + gboolean all_headers); + +Emitted on displaying a message. + +msgview: the MessageView object +msginfo: the MsgInfo message object displayed +all_headers: TRUE if all headers are displayed. FALSE if not. +------------------------------------------------------------------------- +void (* inc_mail_start) (GObject *obj, + PrefsAccount *account); + +Emitted on the start of receiving. + +account: receive target account (PrefsAccount) +------------------------------------------------------------------------- +void (* inc_mail_finished) (GObject *obj, + gint new_messages); + +Emitted on the end of receiving. + +new_messages: number of received messages +------------------------------------------------------------------------- +void (* prefs_common_open) (GObject *obj, + GtkWidget *window); + +Emitted on opening common preferences dialog. + +window: dialog window (GtkWindow) +------------------------------------------------------------------------- +void (* prefs_account_open) (GObject *obj, + PrefsAccount *account, + GtkWidget *window); + +Emitted on opening account preferences dialog. + +window: dialog window (GtkWindow) +------------------------------------------------------------------------- +void (* prefs_filter_open) (GObject *obj, + GtkWidget *window); + +Emitted on opening filter rule preferences dialog. + +window: dialog window (GtkWindow) +------------------------------------------------------------------------- +void (* prefs_filter_edit_open) (GObject *obj, + FilterRule *rule, + const gchar *header, + const gchar *key, + GtkWidget *window); + +Emitted on opening filter rule edit dialog. + +window: dialog window (GtkWindow) +------------------------------------------------------------------------- +void (* prefs_template_open) (GObject *obj, + GtkWidget *window); + +Emitted on opening template dialog. + +window: dialog window (GtkWindow) +------------------------------------------------------------------------- +void (* plugin_manager_open) (GObject *obj, + GtkWidget *window); + +Emitted on opening plug-in manager dialog. + +window: dialog window (GtkWindow) +------------------------------------------------------------------------- +void (* main_window_toolbar_changed) (GObject *obj); + +Emitted on toolbar change of main window. +Use syl_plugin_main_window_get_toolbar() to get main window toolbar object. +------------------------------------------------------------------------- +void (* compose_toolbar_changed) (GObject *obj, gpointer compose); + +Emitted on toolbar change of compose window. +Use syl_plugin_compose_get_toolbar() to get compose toolbar object. + +compose: Compose object +------------------------------------------------------------------------- +void (* compose_attach_changed) (GObject *obj, gpointer compose); + +Emitted when attachments in compose window are changed. +Use syl_plugin_get_attach_list() to get the list of current attachments. + +compose: Compose object +------------------------------------------------------------------------- + +* libsylph-0 + +The following signals can be used by passing GObject obtained by +syl_app_get() to the first argument of g_signal_connect(). + +Example: + +void init_done_cb(GObject *obj, gpointer data) +{ + ... +} + + g_signal_connect(syl_app_get(), "init-done", G_CALLBACK(init_done_cb), + data); + +------------------------------------------------------------------------- +void (* init_done) (GObject *obj) + +Emitted when the initialization of application completes. +------------------------------------------------------------------------- +void (* app_exit) (GObject *obj) + +Emitted when application exits. +------------------------------------------------------------------------- +void (* app_force_exit) (GObject *obj) + +Emitted when application is forced to exit (no confirmation). +(ex: sylpheed --exit) +------------------------------------------------------------------------- +void (* add_msg) (GObject *obj, FolderItem *item, const gchar *file, guint num) + +Emitted when a message (number num) is added into folder item. +------------------------------------------------------------------------- +void (* remove_msg) (GObject *obj, FolderItem *item, const gchar *file, + guint num) + +Emitted when a message (number num) is removed from folder item. +------------------------------------------------------------------------- +void (* remove_all_msg) (GObject *obj, FolderItem *item) + +Emitted when all messages are removed from folder item. +------------------------------------------------------------------------- +void (* remove_folder) (GObject *obj, FolderItem *item) + +Emitted when folder item is removed. +------------------------------------------------------------------------- +void (* move_folder) (GObject *obj, FolderItem *item, const gchar *old_id, + const gchar *new_id) + +Emitted when folder item is moved (renamed) from old_id to new_id. +old_id and new_id are folder identifier strings. +------------------------------------------------------------------------- +void (* folderlist_updated) (GObject *obj) + +Emitted when folder information is modified and folderlist.xml, which +contains folder list, is updated. +------------------------------------------------------------------------- +void (* account_updated) (GObject *obj) + +Emitted on the update of account information. +It will not be emitted if it is locked by account_update_lock(), though. +------------------------------------------------------------------------- + + +Sample plug-ins +=============== + +There is sample plug-ins under the 'plugin' directory. +These plug-ins will not be installed with 'make install'. +It is required to enter the directory plugin/* and run +'make install-plugin'. + +Test Plug-in +------------ + +The 'test' plug-in has the basic structure of Sylpheed plug-in and the +following process: + +- Output string "test plug-in loaded!" to stdout on load +- Get folder list and output to stdout +- Get Sylpheed version string and output to stdout +- Get the main window and put it in front +- Add sub widget under the folder view +- Add 'Plugin test' menu item on the 'Tools' menu +- When 'Plugin test' menu is selected, a window with a button named + 'Click this button' is displayed. When it is clicked, a message is displayed +- Capture the following events and show messages: application initialization + and exiting, folder view context menu popup, creating and destroying compose + window, sending messages +- Capture the text view context menu popup event and add a menu item + +Attachment Tool Plug-in +----------------------- + +This is a plug-in for handling messages with attached files. + +See plugin/attachment_tool/README for the details. + + +About license +============= + +It is required that a plug-in DLL dynamically loaded by Sylpheed is GPL or +GPL-compatible license (ex. modified BSD license) based on the GPL clause +because the license of Sylpheed itself is GPL. + +If you want to apply non-GPL license like proprietary license to your plug-in, +you must make the module an independent executable file, and make it work with +inter-process communication with a DLL. -- cgit v1.3