path: root/PLUGIN.ja.txt

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 でコンテキストメニューをポップアップしたときに発行される
シグナルです。
-------------------------------------------------------------------------
void (* summaryview_menu_popup)  (GObject *obj, gpointer ifactory);

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

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

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

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

menu: コンテキストメニューオブジェクト
textview: GtkTextView オブジェクト
uri: URI の上でメニューを表示した場合その URI 文字列
selected_text: テキストビューでテキストが選択されている場合、その文字列
msginfo: テキストビューで表示されているメッセージの MsgInfo オブジェクト
-------------------------------------------------------------------------
gboolean (* compose_send)       (GObject        *obj,
                                 gpointer        compose,
                                 gint            compose_mode,
                                 gint            send_mode,
                                 const gchar    *msg_file,
                                 GSList         *to_list);

作成したメッセージが送信されようとするときに発行されるシグナルです。
FALSE を返すと、メッセージは通常通り送信されます。
TRUE を返すと、送信はキャンセルされます。

compose: Compose オブジェクト
compose_mode: ComposeMode enum
send_mode: 0: 即座に送信 1: 送信待ちに入れて後で送信
msg_file: 作成したメッセージファイルのパス
to_list: 宛先のリスト
-------------------------------------------------------------------------
void (* messageview_show)       (GObject        *obj,
                                 gpointer        msgview,
                                 MsgInfo        *msginfo,
                                 gboolean        all_headers);

メッセージを表示するときに発行されるシグナルです。

msgview: MessageView オブジェクト
msginfo: 表示された MsgInfo メッセージオブジェクト
all_headers: 全ヘッダ表示時は TRUE。一部のみ表示時は FALSE。
-------------------------------------------------------------------------
void (* inc_mail_start)         (GObject        *obj,
                                 PrefsAccount   *account);

受信開始時に発行されるシグナルです。

account: 受信対象のアカウント (PrefsAccount)
-------------------------------------------------------------------------
void (* inc_mail_finished)      (GObject        *obj,
                                 gint            new_messages);

受信終了時に発行されるシグナルです。

new_messages: 受信したメッセージ数
-------------------------------------------------------------------------
void (* prefs_common_open)      (GObject        *obj,
                                 GtkWidget      *window);

全般の設定ダイアログを開いたときに発行されるシグナルです。

window: ダイアログウィンドウ (GtkWindow)
-------------------------------------------------------------------------
void (* prefs_account_open)     (GObject        *obj,
                                 PrefsAccount   *account,
                                 GtkWidget      *window);

アカウント設定ダイアログを開いたときに発行されるシグナルです。

window: ダイアログウィンドウ (GtkWindow)
-------------------------------------------------------------------------
void (* prefs_filter_open)      (GObject        *obj,
                                 GtkWidget      *window);

振り分けルール設定ダイアログを開いたときに発行されるシグナルです。

window: ダイアログウィンドウ (GtkWindow)
-------------------------------------------------------------------------
void (* prefs_filter_edit_open) (GObject        *obj,
                                 FilterRule     *rule,
                                 const gchar    *header,
                                 const gchar    *key,
                                 GtkWidget      *window);

振り分けルール編集ダイアログを開いたときに発行されるシグナルです。

window: ダイアログウィンドウ (GtkWindow)
-------------------------------------------------------------------------
void (* prefs_template_open)    (GObject        *obj,
                                 GtkWidget      *window);

テンプレートダイアログを開いたときに発行されるシグナルです。

window: ダイアログウィンドウ (GtkWindow)
-------------------------------------------------------------------------
void (* plugin_manager_open)    (GObject        *obj,
                                 GtkWidget      *window);

プラグインの管理ダイアログを開いたときに発行されるシグナルです。

window: ダイアログウィンドウ (GtkWindow)
-------------------------------------------------------------------------
void (* main_window_toolbar_changed) (GObject *obj);

メインウィンドウのツールバー変更時に発行されるシグナルです。
メインウィンドウのツールバーオブジェクトを取得する場合は
syl_plugin_main_window_get_toolbar() を使用してください。
-------------------------------------------------------------------------
void (* compose_toolbar_changed)     (GObject *obj, gpointer compose);

メッセージ作成ウィンドウのツールバー変更時に発行されるシグナルです。
メッセージ作成ウィンドウのツールバーオブジェクトを取得する場合は
syl_plugin_compose_get_toolbar() を使用してください。
-------------------------------------------------------------------------
void (* compose_attach_changed)     (GObject *obj, gpointer compose);

メッセージ作成ウィンドウ上の添付ファイルが変更された場合に発行される
シグナルです。現在の添付ファイルのリストを取得する場合は
syl_plugin_get_attach_list() を使用してください。

compose: Compose オブジェクト
-------------------------------------------------------------------------

* 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 (* app_force_exit) (GObject *obj)

アプリケーションが強制的(確認なし)に終了するときに発行されます。
(例: sylpheed --exit)
-------------------------------------------------------------------------
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 ファイルが
更新されたときに発行されます。
-------------------------------------------------------------------------
void (* account_updated) (GObject *obj)

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


サンプルプラグイン
==================

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

Test Plug-in
------------

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

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

Attachment Tool Plug-in
-----------------------

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

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


ライセンスについて
==================

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

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