Sylpheed

Sylpheed プラグイン仕様

=======================

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

 +----------+    +----------------------+     +-----------+

 | Sylpheed |----| libsylpheed-plugin-0 |--+--| Plug-in A |

 +----------+    +----------------------+  |  +-----------+

Sylpheed 本体    プラグインインタフェース  |  プラグイン DLL

                 ライブラリ             +--+

        |        +------------+         |  |  +-----------+

        +--------| libsylph-0 |---------+  +--| Plug-in B |

                 +------------+               +-----------+

                 LibSylph メールライブラリ

Sylpheed は起動時にプラグインディレクトリにインストールされている

プラグイン DLL をメモリにロードします。

プラグインは libsylpheed-plugin-0 と libsylph-0 ライブラリで

提供されている API を通してのみ Sylpheed の機能にアクセスできます。

プラグイン API には、プラグインが直接呼び出す関数群と、

GObject のシグナル機構を利用して、特定のイベントが発生した場合に

コールバック関数を呼び出すものの2種類があります。

プラグイン機構は libsylph/sylmain.[ch] と src/plugin.[ch] で実装されて

います。

プラグイン API

==============

Sylpheed から利用する関数

-------------------------

-------------------------------------------------------------------------

void syl_plugin_signal_connect  (const gchar *name, GCallback callback,

                                 gpointer data);

SylPlugin オブジェクト(ライブラリ内部で保持)で利用できるシグナルに

接続します。シグナルを受け取るコールバック関数の仕様は通常の GObject と

同様です。

利用できるシグナルに関してはシグナルの一覧を参照してください。

-------------------------------------------------------------------------

void syl_plugin_signal_disconnect(gpointer func, gpointer data);

syl_plugin_signal_connect() で接続したシグナルを解除します。

-------------------------------------------------------------------------

void syl_plugin_signal_emit(const gchar *name, ...);

SylPlugin オブジェクトのシグナルを発行します。

-------------------------------------------------------------------------

gint syl_plugin_init_lib        (void);

libsylpheed-plugin-0 ライブラリの初期化を行います。

-------------------------------------------------------------------------

gint syl_plugin_load            (const gchar *file);

プラグイン DLL ファイルをメモリにロードします。

-------------------------------------------------------------------------

gint syl_plugin_load_all        (const gchar *dir);

指定したディレクトリ内のプラグイン DLL ファイルをメモリにロードします。

-------------------------------------------------------------------------

void syl_plugin_unload_all      (void);

ロードしたすべてのプラグインをアンロードします。

-------------------------------------------------------------------------

GSList *syl_plugin_get_module_list      (void);

現在メモリにロードされているプラグインのリストを取得します。

GModule 構造体へのポインタのリストが返ります。

リストはライブラリ内部で保持しているため、解放できません。

-------------------------------------------------------------------------

SylPluginInfo *syl_plugin_get_info      (GModule *module);

プラグインの情報を取得します。情報は SylPluginInfo 構造体で返ります。

-------------------------------------------------------------------------

gboolean syl_plugin_check_version       (GModule *module);

プラグインインタフェースのバージョンを比較し、互換性があるかどうかを

確認します。バージョンが一致する場合は TRUE 、一致しない場合は FALSE

が返ります。

-------------------------------------------------------------------------

gint syl_plugin_add_symbol              (const gchar *name, gpointer sym);

ライブラリにシンボル名とそれに関連付けられるポインタ値を登録します。

-------------------------------------------------------------------------

gpointer syl_plugin_lookup_symbol       (const gchar *name);

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

-------------------------------------------------------------------------

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

--------------------------------------

-------------------------------------------------------------------------

void plugin_load(void)

プラグインのロード時に Sylpheed から呼び出されます。

ここでプラグインの初期化処理などを行います。

-------------------------------------------------------------------------

void plugin_unload(void)

プラグインのアンロード時に Sylpheed から呼び出されます。

ここでプラグインの後処理などを行います。

-------------------------------------------------------------------------

SylPluginInfo *plugin_info(void)

プラグインの情報を格納する構造体を Sylpheed に返すための関数です。

通常は静的な構造体へのポインタを返します。

-------------------------------------------------------------------------

gint plugin_interface_version(void)

プラグイン API のインタフェースのバージョンを Sylpheed に返すための

関数です。プラグインでは通常は定数 SYL_PLUGIN_INTERFACE_VERSION を返し、

Sylpheed ではこの値を Sylpheed 本体側の値と比較し、互換性のあるバージョン

かどうかをチェックします。 Sylpheed 本体のプラグインインタフェースバージョン

はプラグインのプラグインインタフェースバージョン以上である必要があります。

また、インタフェースバージョンのメジャーバージョンが異なる場合も互換性は

なくなります。

例1: Sylpheed のプラグインインタフェースバージョンが 0x0102 で

     プラグインのプラグインインタフェースバージョンが 0x0100 の場合 OK

例2: Sylpheed のプラグインインタフェースバージョンが 0x0102 で

     プラグインのプラグインインタフェースバージョンが 0x0103 の場合 NG

-------------------------------------------------------------------------

プラグインから利用する関数

--------------------------

関数の一覧は plugin.h を参照してください。

シグナルの一覧

--------------

* libsylpheed-plugin-0

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

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

-------------------------------------------------------------------------

void (* plugin_load)    (GObject *obj, GModule *module);

syl_plugin_load() でプラグインをロードしたときに発行されるシグナルです。

-------------------------------------------------------------------------

void (* plugin_unload)  (GObject *obj, GModule *module);

syl_plugin_unload_all() でプラグインをアンロードしたときに発行される

シグナルです。

-------------------------------------------------------------------------

void (* folderview_menu_popup)  (GObject *obj, gpointer ifactory);

FolderView でコンテキストメニューをポップアップしたときに発行される

シグナルです。

-------------------------------------------------------------------------

* libsylph-0

以下のシグナルは g_signal_connect() の第一引数に syl_app_get() で得られる

GObject を渡して使用します。

例:

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)

アプリケーションの初期化が完了した時点で発行されます。

-------------------------------------------------------------------------

void (* app_exit) (GObject *obj)

アプリケーションが終了する時に発行されます。

-------------------------------------------------------------------------

void (* add_msg) (GObject *obj, FolderItem *item, const gchar *file, guint num)

フォルダ item に番号 num のメッセージが追加された時に発行されます。

-------------------------------------------------------------------------

void (* remove_msg) (GObject *obj, FolderItem *item, const gchar *file,

                     guint num)

フォルダ item から番号 num のメッセージが削除される時に発行されます。

-------------------------------------------------------------------------

void (* remove_all_msg) (GObject *obj, FolderItem *item)

フォルダ item からすべてのメッセージが削除されるときに発行されます。

-------------------------------------------------------------------------

void (* remove_folder) (GObject *obj, FolderItem *item)

フォルダ item が削除されるときに発行されます。

-------------------------------------------------------------------------

void (* move_folder) (GObject *obj, FolderItem *item, const gchar *old_id,

                      const gchar *new_id)

フォルダ item が old_id から new_id に移動(リネーム)されるときに

発行されます。 old_id, new_id はフォルダ識別子文字列です。

-------------------------------------------------------------------------

void (* folderlist_updated) (GObject *obj)

フォルダ情報が変更され、フォルダリストを格納した folderlist.xml ファイルが

更新されたときに発行されます。

-------------------------------------------------------------------------

サンプルプラグイン

==================

plugin/test にサンプルプラグインがあります。このプラグインは

make install ではインストールされません。インストールするには

plugin/test ディレクトリに入って make install-plugin を実行してください。

test プラグインは Sylpheed プラグインの基本的な構造に加え、以下の処理を

行います。

- ロード時に標準出力に "test plug-in loaded!" という文字列を出力

- フォルダの一覧を取得し、標準出力に表示

- Sylpheed のバージョン文字列を取得し、標準出力に表示

- メインウィンドウを取得し、前面に出す

- 「ツール」メニューに「Plugin test」メニュー項目を追加

- 「Plugin test」メニューを選択すると、「Click this to quit」という

  ボタンのみのウィンドウを表示し、クリックすると Sylpheed を終了する

ライセンスについて

==================

Sylpheed 本体のライセンスは GPL であるため、 Sylpheed から動的に

読み込まれるプラグイン DLL は、 GPL の規定に基づき、 GPL または

GPL と互換性のあるライセンス(修正 BSD ライセンスなど)である必要が

あります。

プラグインに商用ライセンスなど他のライセンスを適用したい場合は、

そのモジュールを独立した実行ファイルにして、 DLL とプロセス間通信で

連携して動作させる必要があります。