Statistics
| Revision:

root / PLUGIN.txt

History | View | Annotate | Download (15.1 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
gboolean (* compose_send)       (GObject        *obj,
191
                                 gpointer        compose,
192
                                 gint            compose_mode,
193
                                 gint            send_mode,
194
                                 const gchar    *msg_file,
195
                                 GSList         *to_list);
196

    
197
Emitted on a composed message is being sent.
198
If FALSE is returned, the message is sent normally.
199
If TRUE is returned, sending is cancelled.
200

    
201
compose: the Compose object
202
compose_mode: ComposeMode enum
203
send_mode: 0: send immediately 1: queue and send later
204
msg_file: path to the created message file
205
to_list: list of recipients
206
-------------------------------------------------------------------------
207
void (* messageview_show)       (GObject        *obj,
208
                                 gpointer        msgview,
209
                                 MsgInfo        *msginfo,
210
                                 gboolean        all_headers);
211

    
212
Emitted on displaying a message.
213

    
214
msgview: the MessageView object
215
msginfo: the MsgInfo message object displayed
216
all_headers: TRUE if all headers are displayed. FALSE if not.
217
-------------------------------------------------------------------------
218
void (* inc_mail_start)         (GObject        *obj,
219
                                 PrefsAccount   *account);
220

    
221
Emitted on the start of receiving.
222

    
223
account: receive target account (PrefsAccount)
224
-------------------------------------------------------------------------
225
void (* inc_mail_finished)      (GObject        *obj,
226
                                 gint            new_messages);
227

    
228
Emitted on the end of receiving.
229

    
230
new_messages: number of received messages
231
-------------------------------------------------------------------------
232
void (* prefs_common_open)      (GObject        *obj,
233
                                 GtkWidget      *window);
234

    
235
Emitted on opening common preferences dialog.
236

    
237
window: dialog window (GtkWindow)
238
-------------------------------------------------------------------------
239
void (* prefs_account_open)     (GObject        *obj,
240
                                 PrefsAccount   *account,
241
                                 GtkWidget      *window);
242

    
243
Emitted on opening account preferences dialog.
244

    
245
window: dialog window (GtkWindow)
246
-------------------------------------------------------------------------
247
void (* prefs_filter_open)      (GObject        *obj,
248
                                 GtkWidget      *window);
249

    
250
Emitted on opening filter rule preferences dialog.
251

    
252
window: dialog window (GtkWindow)
253
-------------------------------------------------------------------------
254
void (* prefs_filter_edit_open) (GObject        *obj,
255
                                 FilterRule     *rule,
256
                                 const gchar    *header,
257
                                 const gchar    *key,
258
                                 GtkWidget      *window);
259

    
260
Emitted on opening filter rule edit dialog.
261

    
262
window: dialog window (GtkWindow)
263
-------------------------------------------------------------------------
264
void (* prefs_template_open)    (GObject        *obj,
265
                                 GtkWidget      *window);
266

    
267
Emitted on opening template dialog.
268

    
269
window: dialog window (GtkWindow)
270
-------------------------------------------------------------------------
271
void (* plugin_manager_open)    (GObject        *obj,
272
                                 GtkWidget      *window);
273

    
274
Emitted on opening plug-in manager dialog.
275

    
276
window: dialog window (GtkWindow)
277
-------------------------------------------------------------------------
278

    
279
* libsylph-0
280

    
281
The following signals can be used by passing GObject obtained by
282
syl_app_get() to the first argument of g_signal_connect().
283

    
284
Example:
285

    
286
void init_done_cb(GObject *obj, gpointer data)
287
{
288
    ...
289
}
290

    
291
    g_signal_connect(syl_app_get(), "init-done", G_CALLBACK(init_done_cb),
292
                     data);
293

    
294
-------------------------------------------------------------------------
295
void (* init_done) (GObject *obj)
296

    
297
Emitted when the initialization of application completes.
298
-------------------------------------------------------------------------
299
void (* app_exit) (GObject *obj)
300

    
301
Emitted when application exits.
302
-------------------------------------------------------------------------
303
void (* app_force_exit) (GObject *obj)
304

    
305
Emitted when application is forced to exit (no confirmation).
306
(ex: sylpheed --exit)
307
-------------------------------------------------------------------------
308
void (* add_msg) (GObject *obj, FolderItem *item, const gchar *file, guint num)
309

    
310
Emitted when a message (number num) is added into folder item.
311
-------------------------------------------------------------------------
312
void (* remove_msg) (GObject *obj, FolderItem *item, const gchar *file,
313
                     guint num)
314

    
315
Emitted when a message (number num) is removed from folder item.
316
-------------------------------------------------------------------------
317
void (* remove_all_msg) (GObject *obj, FolderItem *item)
318

    
319
Emitted when all messages are removed from folder item.
320
-------------------------------------------------------------------------
321
void (* remove_folder) (GObject *obj, FolderItem *item)
322

    
323
Emitted when folder item is removed.
324
-------------------------------------------------------------------------
325
void (* move_folder) (GObject *obj, FolderItem *item, const gchar *old_id,
326
                      const gchar *new_id)
327

    
328
Emitted when folder item is moved (renamed) from old_id to new_id.
329
old_id and new_id are folder identifier strings.
330
-------------------------------------------------------------------------
331
void (* folderlist_updated) (GObject *obj)
332

    
333
Emitted when folder information is modified and folderlist.xml, which
334
contains folder list, is updated.
335
-------------------------------------------------------------------------
336
void (* account_updated) (GObject *obj)
337

    
338
Emitted on the update of account information.
339
It will not be emitted if it is locked by account_update_lock(), though.
340
-------------------------------------------------------------------------
341

    
342

    
343
Sample plug-ins
344
===============
345

    
346
There is sample plug-ins under the 'plugin' directory.
347
These plug-ins will not be installed with 'make install'.
348
It is required to enter the directory plugin/* and run
349
'make install-plugin'.
350

    
351
Test Plug-in
352
------------
353

    
354
The 'test' plug-in has the basic structure of Sylpheed plug-in and the
355
following process:
356

    
357
- Output string "test plug-in loaded!" to stdout on load
358
- Get folder list and output to stdout
359
- Get Sylpheed version string and output to stdout
360
- Get the main window and put it in front
361
- Add sub widget under the folder view
362
- Add 'Plugin test' menu item on the 'Tools' menu
363
- When 'Plugin test' menu is selected, a window with a button named
364
  'Click this button' is displayed. When it is clicked, a message is displayed
365
- Capture the following events and show messages: application initialization
366
  and exiting, folder view context menu popup, creating and destroying compose
367
  window, sending messages
368
- Capture the text view context menu popup event and add a menu item
369

    
370
Attachment Tool Plug-in
371
-----------------------
372

    
373
This is a plug-in for handling messages with attached files.
374

    
375
See plugin/attachment_tool/README for the details.
376

    
377

    
378
About license
379
=============
380

    
381
It is required that a plug-in DLL dynamically loaded by Sylpheed is GPL or
382
GPL-compatible license (ex. modified BSD license) based on the GPL clause
383
because the license of Sylpheed itself is GPL.
384

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