Statistics
| Revision:

root / PLUGIN.txt

History | View | Annotate | Download (15.1 KB)

1 2174 hiro
Sylpheed Plugin Specification
2
=============================
3
4 2181 hiro
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 2184 hiro
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 2187 hiro
30 2184 hiro
Plug-in API
31
===========
32
33 2187 hiro
Functions used by Sylpheed
34
--------------------------
35 2184 hiro
36
-------------------------------------------------------------------------
37
void syl_plugin_signal_connect  (const gchar *name, GCallback callback,
38
                                 gpointer data);
39
40 2187 hiro
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 2184 hiro
-------------------------------------------------------------------------
45
void syl_plugin_signal_disconnect(gpointer func, gpointer data);
46
47 2187 hiro
Disconnects signals connected by syl_plugin_signal_connect().
48 2184 hiro
-------------------------------------------------------------------------
49
void syl_plugin_signal_emit(const gchar *name, ...);
50
51 2187 hiro
Emits SylPlugin object signals.
52 2184 hiro
-------------------------------------------------------------------------
53
gint syl_plugin_init_lib        (void);
54
55 2187 hiro
Initializes the libsylpheed-plugin-0 library.
56 2184 hiro
-------------------------------------------------------------------------
57
gint syl_plugin_load            (const gchar *file);
58
59 2187 hiro
Loads plug-in DLL files into memory.
60 2184 hiro
-------------------------------------------------------------------------
61
gint syl_plugin_load_all        (const gchar *dir);
62
63 2187 hiro
Loads plug-in DLL files in the specified directory into memory.
64 2184 hiro
-------------------------------------------------------------------------
65
void syl_plugin_unload_all      (void);
66
67 2187 hiro
Unloads all loaded plug-ins.
68 2184 hiro
-------------------------------------------------------------------------
69
GSList *syl_plugin_get_module_list      (void);
70
71 2187 hiro
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 2184 hiro
-------------------------------------------------------------------------
75
SylPluginInfo *syl_plugin_get_info      (GModule *module);
76
77 2187 hiro
Obtains plug-in information. The information is returned as SylPluginInfo
78
struct.
79 2184 hiro
-------------------------------------------------------------------------
80
gboolean syl_plugin_check_version       (GModule *module);
81
82 2187 hiro
Compares plug-in interface versions and checks if the plug-in is compatible.
83
Returns TRUE if the version matches, FALSE otherwise.
84 2184 hiro
-------------------------------------------------------------------------
85
gint syl_plugin_add_symbol              (const gchar *name, gpointer sym);
86
87 2187 hiro
Registers symbol name and pointer value related to it to the library.
88 2184 hiro
-------------------------------------------------------------------------
89
gpointer syl_plugin_lookup_symbol       (const gchar *name);
90
91 2187 hiro
Searches symbol registered by syl_plugin_add_symbol() and returns its
92
pointer value.
93 2184 hiro
-------------------------------------------------------------------------
94
95
96
Functions which must be implemented by plug-ins
97
-----------------------------------------------
98
99
-------------------------------------------------------------------------
100
void plugin_load(void)
101
102 2187 hiro
Called from Sylpheed on plug-in load.
103
Do initialization of plug-in etc. here.
104 2184 hiro
-------------------------------------------------------------------------
105
void plugin_unload(void)
106
107 2187 hiro
Called from Sylpheed on plug-in unload.
108
Do finalization of plug-in etc. here.
109 2184 hiro
-------------------------------------------------------------------------
110
SylPluginInfo *plugin_info(void)
111
112 2187 hiro
Fuction to return struct which stores plug-in information to Sylpheed.
113
It normally returns pointer to static struct.
114 2184 hiro
-------------------------------------------------------------------------
115
gint plugin_interface_version(void)
116
117 2187 hiro
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 2184 hiro
-------------------------------------------------------------------------
129
130
131
Functions used by plug-ins
132
--------------------------
133
134 2552 hiro
Refer to the header file plugin.h for the functions list.
135 2184 hiro
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 2187 hiro
Emitted on plug-in loading by syl_plugin_load().
151 2184 hiro
-------------------------------------------------------------------------
152
void (* plugin_unload)  (GObject *obj, GModule *module);
153
154 2187 hiro
Emitted on plug-in unloading by syl_plugin_unload_all().
155 2184 hiro
-------------------------------------------------------------------------
156
void (* folderview_menu_popup)  (GObject *obj, gpointer ifactory);
157
158 2187 hiro
Emitted on popup of the context menu of FolderView.
159 2184 hiro
-------------------------------------------------------------------------
160 2666 hiro
void (* summaryview_menu_popup)  (GObject *obj, gpointer ifactory);
161
162
Emitted on popup of the context menu of SummaryView.
163
-------------------------------------------------------------------------
164 2527 hiro
void (* compose_created)        (GObject *obj, gpointer compose);
165 2184 hiro
166 2527 hiro
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 2811 hiro
void (* textview_menu_popup)    (GObject *obj,
173
                                 GtkMenu *menu,
174
                                 GtkTextView *textview,
175
                                 const gchar *uri,
176 2821 hiro
                                 const gchar *selected_text,
177
                                 MsgInfo *msginfo);
178 2527 hiro
179 2811 hiro
Emitted on popup of the context menu of TextView.
180
You can add any menu items to the passed GtkMenu.
181 2821 hiro
The menu object will be created on open and destroyed on close, so menu items
182
must be added each time.
183 2811 hiro
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 2821 hiro
msginfo: the MsgInfo message object displayed in the text view
189 2811 hiro
-------------------------------------------------------------------------
190 3243 hiro
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 2811 hiro
197 3243 hiro
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 2184 hiro
* libsylph-0
280
281 2185 hiro
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 2184 hiro
-------------------------------------------------------------------------
295 2185 hiro
void (* init_done) (GObject *obj)
296
297 2187 hiro
Emitted when the initialization of application completes.
298 2185 hiro
-------------------------------------------------------------------------
299
void (* app_exit) (GObject *obj)
300
301 2187 hiro
Emitted when application exits.
302 2185 hiro
-------------------------------------------------------------------------
303 2798 hiro
void (* app_force_exit) (GObject *obj)
304
305
Emitted when application is forced to exit (no confirmation).
306
(ex: sylpheed --exit)
307
-------------------------------------------------------------------------
308 2185 hiro
void (* add_msg) (GObject *obj, FolderItem *item, const gchar *file, guint num)
309
310 2187 hiro
Emitted when a message (number num) is added into folder item.
311 2185 hiro
-------------------------------------------------------------------------
312
void (* remove_msg) (GObject *obj, FolderItem *item, const gchar *file,
313
                     guint num)
314
315 2187 hiro
Emitted when a message (number num) is removed from folder item.
316 2185 hiro
-------------------------------------------------------------------------
317
void (* remove_all_msg) (GObject *obj, FolderItem *item)
318
319 2187 hiro
Emitted when all messages are removed from folder item.
320 2185 hiro
-------------------------------------------------------------------------
321
void (* remove_folder) (GObject *obj, FolderItem *item)
322
323 2187 hiro
Emitted when folder item is removed.
324 2185 hiro
-------------------------------------------------------------------------
325
void (* move_folder) (GObject *obj, FolderItem *item, const gchar *old_id,
326
                      const gchar *new_id)
327
328 2187 hiro
Emitted when folder item is moved (renamed) from old_id to new_id.
329
old_id and new_id are folder identifier strings.
330 2185 hiro
-------------------------------------------------------------------------
331
void (* folderlist_updated) (GObject *obj)
332
333 2187 hiro
Emitted when folder information is modified and folderlist.xml, which
334
contains folder list, is updated.
335 2185 hiro
-------------------------------------------------------------------------
336 2527 hiro
void (* account_updated) (GObject *obj)
337 2185 hiro
338 2527 hiro
Emitted on the update of account information.
339
It will not be emitted if it is locked by account_update_lock(), though.
340
-------------------------------------------------------------------------
341 2185 hiro
342 2527 hiro
343 2666 hiro
Sample plug-ins
344
===============
345 2185 hiro
346 2666 hiro
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 2185 hiro
351 2666 hiro
Test Plug-in
352
------------
353
354 2185 hiro
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 2570 hiro
- Add sub widget under the folder view
362 2185 hiro
- Add 'Plugin test' menu item on the 'Tools' menu
363
- When 'Plugin test' menu is selected, a window with a button named
364 2438 hiro
  '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 2886 hiro
  window, sending messages
368 2811 hiro
- Capture the text view context menu popup event and add a menu item
369 2185 hiro
370 2666 hiro
Attachment Tool Plug-in
371
-----------------------
372 2185 hiro
373 2666 hiro
This is a plug-in for handling messages with attached files.
374
375
See plugin/attachment_tool/README for the details.
376
377
378 2185 hiro
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.