Statistics
| Revision:

root / PLUGIN.txt @ 2886

History | View | Annotate | Download (11.6 KB)

1
Sylpheed Plugin Specification
2
=============================
3

    
4
The following is the architecture of plugin system of Sylpheed.
5

    
6
 +----------+    +----------------------+     +-----------+
7
 | Sylpheed |----| libsylpheed-plugin-0 |--+--| Plug-in A |
8
 +----------+    +----------------------+  |  +-----------+
9
   Sylpheed         Plug-in interface      |   Plug-in DLL
10
                    library             +--+
11
        |        +------------+         |  |  +-----------+
12
        +--------| libsylph-0 |---------+  +--| Plug-in B |
13
                 +------------+               +-----------+
14
                 LibSylph mail library
15

    
16
Sylpheed loads the plug-in DLLs installed in the plug-in directory on
17
startup.
18

    
19
Plug-in can only access the functions of Sylpheed through the APIs provided
20
with libsylpheed-plugin-0 and libsylph-0 library.
21

    
22
There are two kinds of plug-in API. One is called directly from plug-ins,
23
another one utilizes the signal mechanism of GObject and calls the callback
24
functions on specific events.
25

    
26
The plug-in system is implemented in libsylph/sylmain.[ch] and
27
src/plugin.[ch].
28

    
29

    
30
Plug-in API
31
===========
32

    
33
Functions used by Sylpheed
34
--------------------------
35

    
36
-------------------------------------------------------------------------
37
void syl_plugin_signal_connect  (const gchar *name, GCallback callback,
38
                                 gpointer data);
39

    
40
Connects to signals available with SylPlugin object (obtained inside library).
41
The specification of callback functions that receive signals is similar to
42
that of normal GObject.
43
Refer to the signals list for available signals.
44
-------------------------------------------------------------------------
45
void syl_plugin_signal_disconnect(gpointer func, gpointer data);
46

    
47
Disconnects signals connected by syl_plugin_signal_connect().
48
-------------------------------------------------------------------------
49
void syl_plugin_signal_emit(const gchar *name, ...);
50

    
51
Emits SylPlugin object signals.
52
-------------------------------------------------------------------------
53
gint syl_plugin_init_lib        (void);
54

    
55
Initializes the libsylpheed-plugin-0 library.
56
-------------------------------------------------------------------------
57
gint syl_plugin_load            (const gchar *file);
58

    
59
Loads plug-in DLL files into memory.
60
-------------------------------------------------------------------------
61
gint syl_plugin_load_all        (const gchar *dir);
62

    
63
Loads plug-in DLL files in the specified directory into memory.
64
-------------------------------------------------------------------------
65
void syl_plugin_unload_all      (void);
66

    
67
Unloads all loaded plug-ins.
68
-------------------------------------------------------------------------
69
GSList *syl_plugin_get_module_list      (void);
70

    
71
Obtains the list of plug-ins loaded into memory.
72
It returns the list of pointers to GModule struct.
73
The list is obtained by the library internally, so it must not be freed.
74
-------------------------------------------------------------------------
75
SylPluginInfo *syl_plugin_get_info      (GModule *module);
76

    
77
Obtains plug-in information. The information is returned as SylPluginInfo
78
struct.
79
-------------------------------------------------------------------------
80
gboolean syl_plugin_check_version       (GModule *module);
81

    
82
Compares plug-in interface versions and checks if the plug-in is compatible.
83
Returns TRUE if the version matches, FALSE otherwise.
84
-------------------------------------------------------------------------
85
gint syl_plugin_add_symbol              (const gchar *name, gpointer sym);
86

    
87
Registers symbol name and pointer value related to it to the library.
88
-------------------------------------------------------------------------
89
gpointer syl_plugin_lookup_symbol       (const gchar *name);
90

    
91
Searches symbol registered by syl_plugin_add_symbol() and returns its
92
pointer value.
93
-------------------------------------------------------------------------
94

    
95

    
96
Functions which must be implemented by plug-ins
97
-----------------------------------------------
98

    
99
-------------------------------------------------------------------------
100
void plugin_load(void)
101

    
102
Called from Sylpheed on plug-in load.
103
Do initialization of plug-in etc. here.
104
-------------------------------------------------------------------------
105
void plugin_unload(void)
106

    
107
Called from Sylpheed on plug-in unload.
108
Do finalization of plug-in etc. here.
109
-------------------------------------------------------------------------
110
SylPluginInfo *plugin_info(void)
111

    
112
Fuction to return struct which stores plug-in information to Sylpheed.
113
It normally returns pointer to static struct.
114
-------------------------------------------------------------------------
115
gint plugin_interface_version(void)
116

    
117
Function to return plug-in API interface version to Sylpheed.
118
A plug-in normally returns constant value SYL_PLUGIN_INTERFACE_VERSION.
119
Sylpheed compares this value with its own value and checks if it is
120
compatible. Sylpheed's plug-in interface version must be equal to or greater
121
than the plug-in's plug-in interface verson. If the major versions of the
122
interface version differ, they are treated as incompatible.
123

    
124
Ex.1: Sylpheed plug-in interface version: 0x0102
125
      A plug-in plug-in interface version: 0x0100: OK
126
Ex.2: Sylpheed plug-in interface version: 0x0102
127
      A plug-in plug-in interface version: 0x0103: NG
128
-------------------------------------------------------------------------
129

    
130

    
131
Functions used by plug-ins
132
--------------------------
133

    
134
Refer to the header file plugin.h for the functions list.
135

    
136

    
137
Signals list
138
------------
139

    
140
* libsylpheed-plugin-0
141

    
142
Call syl_plugin_signal_connect() to use the following signals.
143

    
144
Example:
145
  syl_plugin_signal_connect("plugin-load", G_CALLBACK(plugin_load_cb), data);
146

    
147
-------------------------------------------------------------------------
148
void (* plugin_load)    (GObject *obj, GModule *module);
149

    
150
Emitted on plug-in loading by syl_plugin_load().
151
-------------------------------------------------------------------------
152
void (* plugin_unload)  (GObject *obj, GModule *module);
153

    
154
Emitted on plug-in unloading by syl_plugin_unload_all().
155
-------------------------------------------------------------------------
156
void (* folderview_menu_popup)  (GObject *obj, gpointer ifactory);
157

    
158
Emitted on popup of the context menu of FolderView.
159
-------------------------------------------------------------------------
160
void (* summaryview_menu_popup)  (GObject *obj, gpointer ifactory);
161

    
162
Emitted on popup of the context menu of SummaryView.
163
-------------------------------------------------------------------------
164
void (* compose_created)        (GObject *obj, gpointer compose);
165

    
166
Emitted on creating 'Compose' message composition window.
167
-------------------------------------------------------------------------
168
void (* compose_destroy)        (GObject *obj, gpointer compose);
169

    
170
Emitted just before 'Compose' message composition window is destroyed.
171
-------------------------------------------------------------------------
172
void (* textview_menu_popup)    (GObject *obj,
173
                                 GtkMenu *menu,
174
                                 GtkTextView *textview,
175
                                 const gchar *uri,
176
                                 const gchar *selected_text,
177
                                 MsgInfo *msginfo);
178

    
179
Emitted on popup of the context menu of TextView.
180
You can add any menu items to the passed GtkMenu.
181
The menu object will be created on open and destroyed on close, so menu items
182
must be added each time.
183

    
184
menu: context menu object
185
textview: GtkTextView object
186
uri: URI string if the menu popups on an URI
187
selected_text: string if a string is selected on the text view
188
msginfo: the MsgInfo message object displayed in the text view
189
-------------------------------------------------------------------------
190

    
191
* libsylph-0
192

    
193
The following signals can be used by passing GObject obtained by
194
syl_app_get() to the first argument of g_signal_connect().
195

    
196
Example:
197

    
198
void init_done_cb(GObject *obj, gpointer data)
199
{
200
    ...
201
}
202

    
203
    g_signal_connect(syl_app_get(), "init-done", G_CALLBACK(init_done_cb),
204
                     data);
205

    
206
-------------------------------------------------------------------------
207
void (* init_done) (GObject *obj)
208

    
209
Emitted when the initialization of application completes.
210
-------------------------------------------------------------------------
211
void (* app_exit) (GObject *obj)
212

    
213
Emitted when application exits.
214
-------------------------------------------------------------------------
215
void (* app_force_exit) (GObject *obj)
216

    
217
Emitted when application is forced to exit (no confirmation).
218
(ex: sylpheed --exit)
219
-------------------------------------------------------------------------
220
void (* add_msg) (GObject *obj, FolderItem *item, const gchar *file, guint num)
221

    
222
Emitted when a message (number num) is added into folder item.
223
-------------------------------------------------------------------------
224
void (* remove_msg) (GObject *obj, FolderItem *item, const gchar *file,
225
                     guint num)
226

    
227
Emitted when a message (number num) is removed from folder item.
228
-------------------------------------------------------------------------
229
void (* remove_all_msg) (GObject *obj, FolderItem *item)
230

    
231
Emitted when all messages are removed from folder item.
232
-------------------------------------------------------------------------
233
void (* remove_folder) (GObject *obj, FolderItem *item)
234

    
235
Emitted when folder item is removed.
236
-------------------------------------------------------------------------
237
void (* move_folder) (GObject *obj, FolderItem *item, const gchar *old_id,
238
                      const gchar *new_id)
239

    
240
Emitted when folder item is moved (renamed) from old_id to new_id.
241
old_id and new_id are folder identifier strings.
242
-------------------------------------------------------------------------
243
void (* folderlist_updated) (GObject *obj)
244

    
245
Emitted when folder information is modified and folderlist.xml, which
246
contains folder list, is updated.
247
-------------------------------------------------------------------------
248
void (* account_updated) (GObject *obj)
249

    
250
Emitted on the update of account information.
251
It will not be emitted if it is locked by account_update_lock(), though.
252
-------------------------------------------------------------------------
253

    
254

    
255
Sample plug-ins
256
===============
257

    
258
There is sample plug-ins under the 'plugin' directory.
259
These plug-ins will not be installed with 'make install'.
260
It is required to enter the directory plugin/* and run
261
'make install-plugin'.
262

    
263
Test Plug-in
264
------------
265

    
266
The 'test' plug-in has the basic structure of Sylpheed plug-in and the
267
following process:
268

    
269
- Output string "test plug-in loaded!" to stdout on load
270
- Get folder list and output to stdout
271
- Get Sylpheed version string and output to stdout
272
- Get the main window and put it in front
273
- Add sub widget under the folder view
274
- Add 'Plugin test' menu item on the 'Tools' menu
275
- When 'Plugin test' menu is selected, a window with a button named
276
  'Click this button' is displayed. When it is clicked, a message is displayed
277
- Capture the following events and show messages: application initialization
278
  and exiting, folder view context menu popup, creating and destroying compose
279
  window, sending messages
280
- Capture the text view context menu popup event and add a menu item
281

    
282
Attachment Tool Plug-in
283
-----------------------
284

    
285
This is a plug-in for handling messages with attached files.
286

    
287
See plugin/attachment_tool/README for the details.
288

    
289

    
290
About license
291
=============
292

    
293
It is required that a plug-in DLL dynamically loaded by Sylpheed is GPL or
294
GPL-compatible license (ex. modified BSD license) based on the GPL clause
295
because the license of Sylpheed itself is GPL.
296

    
297
If you want to apply non-GPL license like proprietary license to your plug-in,
298
you must make the module an independent executable file, and make it work with
299
inter-process communication with a DLL.