この文書は WeeChat リレープロトコルについて述べたものです: リレープロトコルとは、WeeChat データをクライアントに中継するためのもので、多くの場合クライアントはリモートインターフェイスを指します。

1. はじめに

1.1. 用語

この文書では以下の用語を利用します:

  • リレー: これは relay プラグインを備えた WeeChat を指し、 "サーバ" のように振る舞い、クライアント からの接続を受け付けます

  • クライアント: これは他のソフトウェアのことを指し、ネットワークを介して リレー に接続します; 多くの場合、クライアント はリモートインターフェイスのことを指します。

1.2. ネットワーク図

以下の図に示すようにクライアントリレー に接続しています:

                                               ┌────────────────┐ ワークステーション
 ┌────────┐                                ┌───┤ クライアント 1 │ (Linux、Windows、
 │  irc   │◄──┐  ╔═══════════╤════════╗    │   └────────────────┘ BSD、Mac OS X ...)
 └────────┘   └──╢           │        ║◄───┘   ┌────────────────┐
   ......        ║  WeeChat  │ リレー ║◄───────┤ クライアント 2 │ 携帯デバイス
 ┌────────┐   ┌──╢           │        ║◄───┐   └────────────────┘ (Android、iPhone ...)
 │ jabber │◄──┘  ╚═══════════╧════════╝    │      ......
 └────────┘                                │   ┌────────────────┐
   ......                                  └───┤ クライアント N │ その他のデバイス
                                               └────────────────┘


└────────────┘   └────────────────────┘╘══════╛└──────────────────────────────────────┘
 ネットワーク           ncurses         リレー            リモートインターフェイス
    サーバ          インターフェイス   プロトコル
Note
この文書で述べる全てのクライアントはリレー プラグインの weechat プロトコルを使っています。またリレー プラグインは IRC クライアントからの接続を受け入れることができます、この場合リレー プラグインは IRC プロキシ のように振舞います (この文書では説明しません)。

2. プロトコルの一般的説明

  • リレー プラグインは新しい接続を受け入れるために IP/port をリッスンし、クライアント は TCP ソケットを使ってリレー に接続します。

  • クライアント の数はオプション relay.network.max_clients で制限されています。

  • それぞれのクライアント が自分以外のクライアントと協調して動くことはできません。

  • クライアント からリレー へのメッセージをコマンド と呼び、これはテキスト形式 (文字列) で送信されます。

  • リレー からクライアント へのメッセージをメッセージ と呼び、これはバイナリデータとして送信されます。

3. コマンド (クライアント → リレー)

コマンドのフォーマットは以下です: "(id) command arguments\n".

フィールドは:

  • id: リレー からの応答に含まれる任意指定のメッセージ識別子; 識別子は必ず括弧で括り、アンダースコア ("_") を最初につけるのは禁止されています (アンダースコアが最初についている識別子は WeeChat event メッセージ用に予約されています)

  • command: コマンド (以下のテーブルを参照)

  • arguments: コマンドに対する任意指定の引数 (複数の引数を渡す場合は空白で区切ってください)。

利用可能なコマンドのリスト (詳しくは次の章を参照):

コマンド 説明

init

リレー 接続を初期化

hdata

hdata を要求

info

インフォ を要求

infolist

インフォリスト を要求

nicklist

ニックネームリスト を要求

input

バッファにデータを送信 (テキストまたはコマンド)

sync

バッファを同期 (バッファの最新情報を取得)

desync

バッファを非同期 (バッファの更新を止める)

quit

リレー から切断

3.1. init

リレー 接続を初期化。リレー に送るコマンドは必ずこのコマンドから始めてください。リレー がこのコマンドを受信していない場合、リレー は最初のコマンドを受け取った時点で警告無しに接続を閉じます。

構文:

init [<option>=<value>,[<option>=<value>,...]]

引数:

  • option: 以下のうちの 1 つ:

    • password: リレー の認証用パスワード (WeeChat の relay.network.password オプション)

    • compression: 圧縮タイプ:

      • zlib: リレー から受信するメッセージに対して zlib 圧縮を使う

      • off: 圧縮を使わない

Note
リレーzlib 圧縮をサポートする場合、zlib 圧縮はデフォルトで有効化されます。

例:

# 初期化、デフォルト設定の zlib を使用 (WeeChat がサポートする場合)
init password=mypass

# 初期化、圧縮を使わない
init password=mypass,compression=off

3.2. hdata

hdata を要求。

構文:

(id) hdata <path> [<keys>]

引数:

  • path: hdata へのパス、フォーマットは: "hdata:pointer/var/var/…/var"、最後の var に対応する hdata が返されます:

    • hdata: hdata の名前

    • pointer: ポインタ ("0x12345") またはリスト名 (例: "gui_buffers") (番号も可能、以下を参照)

    • var: 親 hdata に含まれる変数名 (パスで言う 1 つ前の名前) (番号も可能、以下を参照)

  • keys: hdata で返すキーのコンマ区切りリスト (指定しなかった場合、全てのキーが返されます。強大な hdata 構造体の場合全てのキーを返すことはお勧めしません)

ポインタと変数の後に番号を指定することができます。フォーマットは "(N)"。可能な値は:

  • 正数: N 回次の要素への反復を繰り返す

  • 負数: N 回前の要素への反復を繰り返す

  • *: 最後の要素まで、次の要素への反復を繰り返す

例:

# すべてのバッファを要求、"buffer" 型の hdata が返される
# それぞれのバッファについて "number" と "name" キーが返される
hdata buffer:gui_buffers(*) number,name

# バッファの全ての行を要求、"line_data" 型の hdata が返される
# 全てのキーが返される
hdata buffer:gui_buffers(*)/lines/first_line(*)/data

# 最初のバッファの完全な名前を要求
hdata buffer:gui_buffers full_name

3.3. info

インフォ を要求。

構文:

(id) info <name>

引数:

  • name: 読み出すインフォの名前

例:

info version

3.4. infolist

インフォリスト を要求。

Important
インフォリストの内容は実際のデータの複製です。可能な限り hdata コマンドを使ってください、このコマンドはデータを直接読み出すことが可能です (高速、省メモリ、メッセージで返すオブジェクトのサイズが小さいです)。

構文:

(id) infolist <name> [<pointer> [<arguments>]]

引数:

  • name: 取得するインフォリストの名前

  • pointer: ポインタ (任意)

  • arguments: 引数 (任意)

例:

infolist buffer

3.5. nicklist

1 つまたは全てのバッファからニックネームリスト を要求。

Syntax: 構文:

(id) nicklist [<buffer>]

引数:

  • buffer: ポインタ (0x12345) またはバッファの完全な名前 (例: core.weechat または irc.freenode.#weechat)

例:

# 全てのバッファのニックネームリストを要求
nicklist

# irc.freenode.#weechat のニックネームリストを要求
nicklist irc.freenode.#weechat

3.6. input

バッファにデータを送信。

構文:

input <buffer> <data>

引数:

  • buffer: ポインタ (0x12345) またはバッファの完全な名前 (例: core.weechat または irc.freenode.#weechat)

  • data: バッファに送信するデータ: / で始まる場合、バッファ内でコマンドとして実行されます、それ以外の場合、テキストはバッファの入力として送信されます。

例:

input core.weechat /help filter
input irc.freenode.#weechat hello!

3.7. sync

バージョン 0.4.1 で更新。

更新を取得して 1 つまたは複数のバッファを同期。

Important
バッファのデータ (行、…) を要求した直後にこのコマンドを送信することをお勧めします。1 つのメッセージの中にこのコマンドを含める (改行文字 "\n" で区切る) ことで同時に送信できます。

構文:

sync [<buffer>[,<buffer>...] <option>[,<option>...]]

引数:

  • buffer: ポインタ (0x12345) またはバッファの完全な名前 (例: core.weechat または irc.freenode.#weechat); 全てのバッファを指定するには "*" を使ってください

  • options: 以下に挙げるキーワード、コンマ区切り ("*" に対するデフォルトは buffers,upgrade,buffer,nicklist'、バッファに対するデフォルトは 'buffer,nicklist):

    • buffers: バッファに関するシグナルを受け取る (オープン/クローズ、移動、リネーム、 マージ/アンマージ、隠す/隠さない); これは名前が "*" の場合のみ利用可能 (WeeChat バージョン 0.4.1 以上で利用可)

    • upgrade: WeeChat アップグレードに関するシグナルを受信 (アップグレード、アップグレードの終了); 名前が "*" のバッファに対してのみ利用可能 (WeeChat バージョン 0.4.1 以上で利用可)

    • buffer: バッファに関するシグナルを受信 (新しい行、型の変更、タイトルの変更、ローカル変数の追加/削除、buffers と同じバッファに関するシグナル) (バージョン 0.4.1 で更新)

    • nicklist: 変更後にニックネームリストを受信

例:

# ニックネームリストを持つ全てのバッファを同期
# (3 つのコマンドは全て等価ですが、
# 将来のバージョンとの互換性を考慮して 1 つ目のコマンドを推奨します)
sync
sync *
sync * buffers,upgrade,buffer,nicklist

# コアバッファを同期
sync core.buffer

# #weechat チャンネルを同期、ニックネームリストは受信しない
sync irc.freenode.#weechat buffer

# 一般的なシグナル + #weechat チャンネルに対する全てのシグナルを取得
sync * buffers,upgrade
sync irc.freenode.#weechat

3.8. desync

バージョン 0.4.1 で更新。

更新を中止して 1 つまたは複数のバッファの同期を中止。

Note
バッファのオプション を削除します。バッファに対する一部のオプションがまだ有効な場合、クライアントはバッファに対するアップデートを受け取ります。

構文:

desync [<buffer>[,<buffer>...] <option>[,<option>...]]

引数:

  • buffer: ポインタ (0x12345) またはバッファの完全な名前 (例: core.weechat または irc.freenode.#weechat); 全てのバッファを指定するには "*" を使ってください

  • options: 以下に挙げるキーワード、コンマ区切り ("*" に対するデフォルトは buffers,upgrade,buffer,nicklist'、バッファに対するデフォルトは 'buffer,nicklist): 値に関する詳しい情報は sync コマンドをご覧ください

Note
buffer に "*" を指定した場合、(名前を使って) 同期されている他のバッファは同期状態が保存されます。
このため "sync *"、"sync irc.freenode.#weechat"、"desync *" の順に送信した場合、WeeChat は #weechat チャンネルに対するアップデートを送信し続けます (アップデートを止めるには、明示してこれを中止しなければいけません)。

例:

# ニックネームリストを持つ全てのバッファの同期を中止
# (3 つのコマンドは全て等価ですが、
# 将来のバージョンとの互換性を考慮して 1 つ目のコマンドを推奨します)
desync
desync *
desync * buffers,upgrade,buffer,nicklist

# #weechat チャンネルのニックネームリストの同期を中止 (バッファは同期する)
desync irc.freenode.#weechat nicklist

# #weechat チャンネルの同期を中止
desync irc.freenode.#weechat

3.9. test

テストコマンド: WeeChat は様々な種類のオブジェクトを返します。

このコマンドは WeeChat が返すバイナリオブジェクトのデコーディングをテストする際に便利です。

Important
このコマンドが返したポインタ値を絶対に使ってはいけません、ポインタ値は無効です。このコマンドを WeeChat が返すメッセージのデコーディングをテストする場合以外に使わないでください。

構文:

test

例:

test

返されるオブジェクト (以下の順番):

型 (メッセージ中)

char

chr

65 ("A")

integer

int

123456

integer

int

-123456

long

lon

1234567890

long

lon

-1234567890

string

str

"a string"

string

str

""

string

str

NULL

buffer

buf

"buffer"

buffer

buf

NULL

pointer

ptr

0x1234abcd

pointer

ptr

NULL

time

tim

1321993456

string の配列

arr str

[ "abc", "de" ]

integer の配列

arr int

[ 123, 456, 789 ]

3.10. ping

WeeChat バージョン 0.4.2 以上で利用可。

WeeChat にメッセージ "_pong" と同じ引数を持つ返信 ping を送信。

このコマンドは WeeChat との接続がまだ保持されいることの確認と応答時間を計測する場合に便利です。

構文:

ping [<arguments>]

例:

ping 1370802127000

3.11. quit

リレー から切断。

構文:

quit

例:

quit

4. メッセージ (リレー → クライアント)

メッセージは以下のフォーマットでバイナリデータとして送信されます (サイズはバイト単位):

┌────────╥─────────────╥────╥────────┬──────────╥───────╥────────┬──────────┐
│ length ║ compression ║ id ║ type 1 │ object 1 ║  ...  ║ type N │ object N │
└────────╨─────────────╨────╨────────┴──────────╨───────╨────────┴──────────┘
 └──────┘ └───────────┘ └──┘ └──────┘ └────────┘         └──────┘ └────────┘
     4          1        ??      3        ??                 3        ??
 └────────────────────┘ └──────────────────────────────────────────────────┘
       ヘッダ (5)                        圧縮されたデータ (??)
 └─────────────────────────────────────────────────────────────────────────┘
                               'length' バイト
  • length (符号なし整数型): メッセージ全体のバイト数 (このフィールドを含む)

  • compression (バイト型): フラグ:

    • 0x00: これ以降のデータは圧縮されていません

    • 0x01: これ以降のデータは zlib で圧縮されています

  • id (文字列型): クライアントが送信した識別子 (コマンド名の前につけられる); コマンドに識別子が含まれない場合は空文字列でも可 (内容を含まない長さゼロの文字列)

  • type (3 文字): 型の種類: 3 文字 (以下の表を参照)

  • object: オブジェクト (以下の表を参照)

4.1. 圧縮

compression フラグが 0x01 の場合、これ以降の全ての データは zlib で圧縮されているため、処理前に必ず展開してください。

4.2. 識別子

識別子 (id) には 2 種類あります:

  • クライアント が送信する id: リレーid を含む受信メッセージに対して同じ id を付けて応答します。

  • イベントの id: 一部のイベントで、リレークライアント に向けて特別な、アンダースコアで始まる、id を含むメッセージを送信します (以下の表を参照)

WeeChat の予約識別子:

識別子 sync で受信 送信されるデータ 説明 推奨するクライアントの挙動

_buffer_opened

buffers / buffer

hdata: buffer

バッファのオープン

バッファを開く

_buffer_moved

buffers / buffer

hdata: buffer

バッファの移動

バッファを移動

_buffer_merged

buffers / buffer

hdata: buffer

バッファのマージ

バッファをマージ

_buffer_unmerged

buffers / buffer

hdata: buffer

バッファのアンマージ

バッファをアンマージ

_buffer_hidden

buffers / buffer

hdata: buffer

バッファを隠す

バッファを隠す

_buffer_unhidden

buffers / buffer

hdata: buffer

バッファを隠すことを止める

バッファを隠すことを止める

_buffer_renamed

buffers / buffer

hdata: buffer

バッファのリネーム

バッファをリネーム

_buffer_title_changed

buffers / buffer

hdata: buffer

バッファのタイトル変更

バッファのタイトルを変更

_buffer_cleared

buffer

hdata: buffer

バッファのクリア

バッファをクリア

_buffer_type_changed

buffer

hdata: buffer

バッファの種類変更

バッファの種類を変更

_buffer_localvar_added

buffer

hdata: buffer

ローカル変数の追加

バッファに対するローカル変数を追加

_buffer_localvar_changed

buffer

hdata: buffer

ローカル変数の変更

バッファに対するローカル変数を変更

_buffer_localvar_removed

buffer

hdata: buffer

ローカル変数を削除

バッファからローカル変数を削除

_buffer_line_added

buffer

hdata: line

バッファへの行追加

バッファに行を表示

_buffer_closing

buffers / buffer

hdata: buffer

バッファのクローズ

バッファを閉じる

_nicklist

nicklist

hdata: nicklist_item

バッファのニックネームリスト

ニックネームリストを置換

_nicklist_diff

nicklist

hdata: nicklist_item

バッファに対するニックネームの差分

ニックネームリストを更新

_pong

(常に)

string: ping arguments

"ping" に対する応答

応答時間の測定

_upgrade

upgrade

(空)

WeeChat のアップグレード中

WeeChat との同期を中止 (または切断)

_upgrade_ended

upgrade

(空)

WeeChat のアップグレード終了

WeeChat との同期および再同期

4.2.1. _buffer_opened

このメッセージは WeeChat が "buffer_opened" シグナルを送信する際にクライアントに送られます。

hdata として送られるデータ:

名前 説明

number

integer

バッファ番号 (≥ 1)

full_name

string

完全な名前 (例: irc.freenode.#weechat)

short_name

string

短い名前 (例: #weechat)

nicklist

integer

バッファがニックネームリストを持つ場合 1、それ以外は 0

title

string

バッファのタイトル

local_variables

hashtable

ローカル変数

prev_buffer

pointer

前のバッファへのポインタ

next_buffer

pointer

次のバッファへのポインタ

例: freenode の #weechat チャンネルに参加、新しいバッファは irc.freenode.#weechat: