Statistics
| Revision:

root / PLUGIN.ja.txt @ 2821

History | View | Annotate | Download (14.7 KB)

1
Sylpheed プラグイン仕様
2
=======================
3

    
4
Sylpheed のプラグイン機構の構成は以下のようになっています。
5

    
6
 +----------+    +----------------------+     +-----------+
7
 | Sylpheed |----| libsylpheed-plugin-0 |--+--| Plug-in A |
8
 +----------+    +----------------------+  |  +-----------+
9
Sylpheed 本体    プラグインインタフェース  |  プラグイン DLL
10
                 ライブラリ             +--+
11
        |        +------------+         |  |  +-----------+
12
        +--------| libsylph-0 |---------+  +--| Plug-in B |
13
                 +------------+               +-----------+
14
                 LibSylph メールライブラリ
15

    
16
Sylpheed は起動時にプラグインディレクトリにインストールされている
17
プラグイン DLL をメモリにロードします。
18

    
19
プラグインは libsylpheed-plugin-0 と libsylph-0 ライブラリで
20
提供されている API を通してのみ Sylpheed の機能にアクセスできます。
21

    
22
プラグイン API には、プラグインが直接呼び出す関数群と、
23
GObject のシグナル機構を利用して、特定のイベントが発生した場合に
24
コールバック関数を呼び出すものの2種類があります。
25

    
26
プラグイン機構は libsylph/sylmain.[ch] と src/plugin.[ch] で実装されて
27
います。
28

    
29

    
30
プラグイン API
31
==============
32

    
33
Sylpheed から利用する関数
34
-------------------------
35

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

    
40
SylPlugin オブジェクト(ライブラリ内部で保持)で利用できるシグナルに
41
接続します。シグナルを受け取るコールバック関数の仕様は通常の GObject と
42
同様です。
43
利用できるシグナルに関してはシグナルの一覧を参照してください。
44
-------------------------------------------------------------------------
45
void syl_plugin_signal_disconnect(gpointer func, gpointer data);
46

    
47
syl_plugin_signal_connect() で接続したシグナルを解除します。
48
-------------------------------------------------------------------------
49
void syl_plugin_signal_emit(const gchar *name, ...);
50

    
51
SylPlugin オブジェクトのシグナルを発行します。
52
-------------------------------------------------------------------------
53
gint syl_plugin_init_lib        (void);
54

    
55
libsylpheed-plugin-0 ライブラリの初期化を行います。
56
-------------------------------------------------------------------------
57
gint syl_plugin_load            (const gchar *file);
58

    
59
プラグイン DLL ファイルをメモリにロードします。
60
-------------------------------------------------------------------------
61
gint syl_plugin_load_all        (const gchar *dir);
62

    
63
指定したディレクトリ内のプラグイン DLL ファイルをメモリにロードします。
64
-------------------------------------------------------------------------
65
void syl_plugin_unload_all      (void);
66

    
67
ロードしたすべてのプラグインをアンロードします。
68
-------------------------------------------------------------------------
69
GSList *syl_plugin_get_module_list      (void);
70

    
71
現在メモリにロードされているプラグインのリストを取得します。
72
GModule 構造体へのポインタのリストが返ります。
73
リストはライブラリ内部で保持しているため、解放できません。
74
-------------------------------------------------------------------------
75
SylPluginInfo *syl_plugin_get_info      (GModule *module);
76

    
77
プラグインの情報を取得します。情報は SylPluginInfo 構造体で返ります。
78
-------------------------------------------------------------------------
79
gboolean syl_plugin_check_version       (GModule *module);
80

    
81
プラグインインタフェースのバージョンを比較し、互換性があるかどうかを
82
確認します。バージョンが一致する場合は TRUE 、一致しない場合は FALSE
83
が返ります。
84
-------------------------------------------------------------------------
85
gint syl_plugin_add_symbol              (const gchar *name, gpointer sym);
86

    
87
ライブラリにシンボル名とそれに関連付けられるポインタ値を登録します。
88
-------------------------------------------------------------------------
89
gpointer syl_plugin_lookup_symbol       (const gchar *name);
90

    
91
syl_plugin_add_symbol() で登録したシンボルを検索し、ポインタ値を返します。
92
-------------------------------------------------------------------------
93

    
94

    
95
プラグインが実装しなければならない関数
96
--------------------------------------
97

    
98
-------------------------------------------------------------------------
99
void plugin_load(void)
100

    
101
プラグインのロード時に Sylpheed から呼び出されます。
102
ここでプラグインの初期化処理などを行います。
103
-------------------------------------------------------------------------
104
void plugin_unload(void)
105

    
106
プラグインのアンロード時に Sylpheed から呼び出されます。
107
ここでプラグインの後処理などを行います。
108
-------------------------------------------------------------------------
109
SylPluginInfo *plugin_info(void)
110

    
111
プラグインの情報を格納する構造体を Sylpheed に返すための関数です。
112
通常は静的な構造体へのポインタを返します。
113
-------------------------------------------------------------------------
114
gint plugin_interface_version(void)
115

    
116
プラグイン API のインタフェースのバージョンを Sylpheed に返すための
117
関数です。プラグインでは通常は定数 SYL_PLUGIN_INTERFACE_VERSION を返し、
118
Sylpheed ではこの値を Sylpheed 本体側の値と比較し、互換性のあるバージョン
119
かどうかをチェックします。 Sylpheed 本体のプラグインインタフェースバージョン
120
はプラグインのプラグインインタフェースバージョン以上である必要があります。
121
また、インタフェースバージョンのメジャーバージョンが異なる場合も互換性は
122
なくなります。
123

    
124
例1: Sylpheed のプラグインインタフェースバージョンが 0x0102 で
125
     プラグインのプラグインインタフェースバージョンが 0x0100 の場合 OK
126
例2: Sylpheed のプラグインインタフェースバージョンが 0x0102 で
127
     プラグインのプラグインインタフェースバージョンが 0x0103 の場合 NG
128
-------------------------------------------------------------------------
129

    
130

    
131
プラグインから利用する関数
132
--------------------------
133

    
134
関数の一覧はヘッダファイル plugin.h を参照してください。
135

    
136

    
137
シグナルの一覧
138
--------------
139

    
140
* libsylpheed-plugin-0
141

    
142
以下のシグナルは syl_plugin_signal_connect() を呼び出して使用します。
143

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

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

    
149
syl_plugin_load() でプラグインをロードしたときに発行されるシグナルです。
150
-------------------------------------------------------------------------
151
void (* plugin_unload)  (GObject *obj, GModule *module);
152

    
153
syl_plugin_unload_all() でプラグインをアンロードしたときに発行される
154
シグナルです。
155
-------------------------------------------------------------------------
156
void (* folderview_menu_popup)  (GObject *obj, gpointer ifactory);
157

    
158
FolderView でコンテキストメニューをポップアップしたときに発行される
159
シグナルです。
160
-------------------------------------------------------------------------
161
void (* summaryview_menu_popup)  (GObject *obj, gpointer ifactory);
162

    
163
SummaryView でコンテキストメニューをポップアップしたときに発行される
164
シグナルです。
165
-------------------------------------------------------------------------
166
void (* compose_created)        (GObject *obj, gpointer compose);
167

    
168
Compose メッセージ作成ウィンドウが作成されたときに発行されるシグナルです。
169
-------------------------------------------------------------------------
170
void (* compose_destroy)        (GObject *obj, gpointer compose);
171

    
172
Compose メッセージ作成ウィンドウが破棄される直前に発行されるシグナルです。
173
-------------------------------------------------------------------------
174
void (* textview_menu_popup)    (GObject *obj,
175
                                 GtkMenu *menu,
176
                                 GtkTextView *textview,
177
                                 const gchar *uri,
178
                                 const gchar *selected_text,
179
                                 MsgInfo *msginfo);
180

    
181
TextView でコンテキストメニューをポップアップするときに発行される
182
シグナルです。ここで渡された GtkMenu に対して任意のメニュー項目を
183
追加することができます。
184
メニューオブジェクトはメニューを開くたびに作成され、閉じられると自動的に
185
破棄されるため、毎回メニュー項目を追加する必要があります。
186

    
187
menu: コンテキストメニューオブジェクト
188
textview: GtkTextView オブジェクト
189
uri: URI の上でメニューを表示した場合その URI 文字列
190
selected_text: テキストビューでテキストが選択されている場合、その文字列
191
msginfo: テキストビューで表示されているメッセージの MsgInfo オブジェクト
192
-------------------------------------------------------------------------
193

    
194
* libsylph-0
195

    
196
以下のシグナルは g_signal_connect() の第一引数に syl_app_get() で得られる
197
GObject を渡して使用します。
198

    
199
例:
200

    
201
void init_done_cb(GObject *obj, gpointer data)
202
{
203
    ...
204
}
205

    
206
    g_signal_connect(syl_app_get(), "init-done", G_CALLBACK(init_done_cb),
207
                     data);
208

    
209
-------------------------------------------------------------------------
210
void (* init_done) (GObject *obj)
211

    
212
アプリケーションの初期化が完了した時点で発行されます。
213
-------------------------------------------------------------------------
214
void (* app_exit) (GObject *obj)
215

    
216
アプリケーションが終了する時に発行されます。
217
-------------------------------------------------------------------------
218
void (* app_force_exit) (GObject *obj)
219

    
220
アプリケーションが強制的(確認なし)に終了するときに発行されます。
221
(例: sylpheed --exit)
222
-------------------------------------------------------------------------
223
void (* add_msg) (GObject *obj, FolderItem *item, const gchar *file, guint num)
224

    
225
フォルダ item に番号 num のメッセージが追加された時に発行されます。
226
-------------------------------------------------------------------------
227
void (* remove_msg) (GObject *obj, FolderItem *item, const gchar *file,
228
                     guint num)
229

    
230
フォルダ item から番号 num のメッセージが削除される時に発行されます。
231
-------------------------------------------------------------------------
232
void (* remove_all_msg) (GObject *obj, FolderItem *item)
233

    
234
フォルダ item からすべてのメッセージが削除されるときに発行されます。
235
-------------------------------------------------------------------------
236
void (* remove_folder) (GObject *obj, FolderItem *item)
237

    
238
フォルダ item が削除されるときに発行されます。
239
-------------------------------------------------------------------------
240
void (* move_folder) (GObject *obj, FolderItem *item, const gchar *old_id,
241
                      const gchar *new_id)
242

    
243
フォルダ item が old_id から new_id に移動(リネーム)されるときに
244
発行されます。 old_id, new_id はフォルダ識別子文字列です。
245
-------------------------------------------------------------------------
246
void (* folderlist_updated) (GObject *obj)
247

    
248
フォルダ情報が変更され、フォルダリストを格納した folderlist.xml ファイルが
249
更新されたときに発行されます。
250
-------------------------------------------------------------------------
251
void (* account_updated) (GObject *obj)
252

    
253
アカウント情報が更新されたときに発行されるシグナルです。
254
ただし、 account_update_lock() によってロックされている場合は
255
発行されません。
256
-------------------------------------------------------------------------
257

    
258

    
259
サンプルプラグイン
260
==================
261

    
262
plugin ディレクトリ以下にサンプルプラグインがあります。これらのプラグインは
263
make install ではインストールされません。インストールするには
264
plugin/ 以下の各ディレクトリに入って make install-plugin を実行してください。
265

    
266
Test Plug-in
267
------------
268

    
269
test プラグインは Sylpheed プラグインの基本的な構造に加え、以下の処理を
270
行います。
271

    
272
- ロード時に標準出力に "test plug-in loaded!" という文字列を出力
273
- フォルダの一覧を取得し、標準出力に表示
274
- Sylpheed のバージョン文字列を取得し、標準出力に表示
275
- メインウィンドウを取得し、前面に出す
276
- フォルダビューの下にサブウィジェットを追加
277
- 「ツール」メニューに「Plugin test」メニュー項目を追加
278
- 「Plugin test」メニューを選択すると、「Click this button」という
279
  ボタンのみのウィンドウを表示し、クリックするとメッセージを出力
280
- アプリケーション初期化、終了、フォルダビューのコンテキストメニュー
281
  ポップアップ、メッセージ作成ウィンドウ作成、メッセージ作成ウィンドウ破棄
282
  のイベントを捕捉してメッセージを表示
283
- テキストビューのコンテキストメニュー表示イベントを捕捉してメニュー項目を追加
284

    
285
Attachment Tool Plug-in
286
-----------------------
287

    
288
添付ファイルつきのメッセージを操作するためのプラグインです。
289

    
290
詳細は plugin/attachment_tool/README を参照してください。
291

    
292

    
293
ライセンスについて
294
==================
295

    
296
Sylpheed 本体のライセンスは GPL であるため、 Sylpheed から動的に
297
読み込まれるプラグイン DLL は、 GPL の規定に基づき、 GPL または
298
GPL と互換性のあるライセンス(修正 BSD ライセンスなど)である必要が
299
あります。
300

    
301
プラグインに商用ライセンスなど他のライセンスを適用したい場合は、
302
そのモジュールを独立した実行ファイルにして、 DLL とプロセス間通信で
303
連携して動作させる必要があります。