この文書は 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: コマンドに対する任意指定の引数 (複数の引数を渡す場合は空白で区切ってください)。
利用可能なコマンドのリスト (詳しくは次の章を参照):
コマンド | 説明 |
---|---|
|
リレー 接続を初期化 |
|
hdata を要求 |
|
インフォ を要求 |
|
インフォリスト を要求 |
|
ニックネームリスト を要求 |
|
バッファにデータを送信 (テキストまたはコマンド) |
|
バッファを同期 (バッファの最新情報を取得) |
|
バッファを非同期 (バッファの更新を止める) |
|
リレー から切断 |
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 |
|
|
integer |
|
|
integer |
|
|
long |
|
|
long |
|
|
string |
|
|
string |
|
|
string |
|
|
buffer |
|
|
buffer |
|
|
pointer |
|
|
pointer |
|
|
time |
|
|
string の配列 |
|
|
integer の配列 |
|
|
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 として送られるデータ:
名前 | 型 | 説明 |
---|---|---|
|
integer |
バッファ番号 (≥ 1) |
|
string |
完全な名前 (例: irc.freenode.#weechat) |
|
string |
短い名前 (例: #weechat) |
|
integer |
バッファがニックネームリストを持つ場合 1、それ以外は 0 |
|
string |
バッファのタイトル |
|
hashtable |
ローカル変数 |
|
pointer |
前のバッファへのポインタ |
|
pointer |
次のバッファへのポインタ |
例: freenode の #weechat チャンネルに参加、新しいバッファは irc.freenode.#weechat: