非公式 SSTP/1.x プロトコル仕様書

はじめに

この仕様書は，伺か公式ページ内の旧仕様書，履歴などを元につくられた非公式仕様書であることに注意してください。

独自に書き加えた情報がありますが，検証していないので情報の正確性は保証できません。

概要

SSTP プロトコルはデスクトップキャラクタ「伺か」の開発過程に生み出されたプロトコルであり，他のプログラムが「伺か」キャラクタを「表現体」として使ったり，「伺か」キャラクタのポテンシャルをより強く引き出したりするために使用されます。

「伺か」の本体 MATERIAmainsystem および互換プラットフォームの本体は SSTP サーバとしての機能を持ちます。SSTP サーバは SSTP クライアントと SSTP プロトコルで通信を行い，リクエストに従って様々な動作をします。

このサービスは OS に依存しない形で行われるため，可能性はローカルマシン内で閉じません。インターネット等を経由して別のマシンのクライアントから別のマシンの MATERIAmainsystem に SSTP パケットを送付することや，web サーバからクライアントマシンに対して SSTP パケットを送信すること等も可能です。

ローカルマシン内で閉じない例

TinkerBell

html ファイルに Javascript で記述したスクリプトを cgi により SSTP でゴーストへ通知する。

いもうとネットワークサービス - 毒電波 -

スクリプトを cgi により SSTP でゴーストへ通知する。

SSTP送信CGI

スクリプトを cgi により SSTP でゴーストへ通知する。

send_sstp

スクリプトを cgi により SSTP でゴーストへ通知する。

SSTP としてはローカルで閉じているが，運用上ローカルで閉じない例

SSTP Bottle

ユーザが作成したスクリプトを SSTP Bottle Client を起動中のユーザ全てのゴーストへ通知する。

• Windows - SSTP Bottle Client
• MacOS X - BotCli

SSTP ブラウザ Plug-in for Windows

html ファイルに EMBED 要素として埋め込んだファイル内のスクリプトを SSTP でゴーストへ通知する。

ボトル on IRC

IRC での発言を SAKURA Script として SSTP でゴーストへ通知する。

X-SSTP-Mail

eメールの独自拡張ヘッダ。メールソフトに機能があれば，このヘッダの内容が SSTP としてゴーストに通知されます。いくつかのメールソフトでプラグインが公開されています。

• X-SSTP-Mail Plugin for Becky!V2
• X-SSTP-Mail Plugin for Datula
• X-SSTP-Mail Plugin for EdMax TEST VERSION
• 鶴亀メール用 SSTP マクロセット
• Meadow - sstp.el

動作

MATERIAmainsystem は (標準で) ポート 9801 番をリスニングします。クライアントはこのポートに接続し，SSTPプロトコルでパケットを送付します。送付後，リクエストが正しいか否かに関わらず約2秒以内にステータスコードが返り，リクエストが正しければ MATERIAmainsystem はパケットからデータを取り出し適切な動作をします。

1 つのサーバに接続できるクライアントは 1 つだけで，既にクライアントがいる場合 Conflict が返ります。通信は極めて短時間で終了することを前提としており，終了しなかった場合は Request Timeout で強制切断されます。

リクエスト / レスポンス

リクエスト

NOTIFY SSTP/1.1[CRLF]
Sender: カードキャプター[CRLF]
Event: OnRelease[CRLF]
Charset: UTF-8[CRLF]
[CRLF]

HTTP と同様，行単位処理の発想であり，CR LF で各行がセパレートされ，空行でターミネートされる。

第 1 行目はコマンド行であり，コマンド文字列とこのリクエストのバージョンナンバがセットされる。第 2 行目以降はヘッダ行であり，Key: Value の形式で任意の数のヘッダが続く。このヘッダの最大数は無限であり，順不同である。

HTTP と違い，バージョンナンバがメソッドごとに異なります。

レスポンス

SSTP/1.1 200 OK[CRLF]
[CRLF]

第 1 行目はステータス行であり，SSTP バージョン，ステータスコード，説明句がセットされる。

付加情報がある場合には次のようなレスポンスとなります。

SSTP/1.1 200 OK[CRLF]
[CRLF]
まあまあ[CRLF]
[CRLF]

戻り値は，伺かの場合 Shift_JIS ，SSP の場合リクエストの Charset で返ります。

SSTP/1.1 200 OK[CRLF]
まあまあ[CRLF]
[CRLF]

ステータスコード

SSTP レスポンスメッセージに含まれるステータスコードは HTTP のステータスコードの一部を利用および拡張した物となっています。[参考: RFC 2616 - HTTP/1.1 - 6.1.1 ステータスコードと説明句]

NOTIFY/1.1

NOTIFY は汎用的なイベント通知を行うためのリクエストメソッドです。NOTIFY で渡されたデータは SSTP サーバを介して SHIORI/3.0 リクエストとして Shiori に到達し，Shiori はイベントに対する反応を行います。

NOTIFY SSTP/1.1
Sender: さくら
Event: OnMusicPlay
Reference0: 元祖高木ブー伝説
Reference1: 筋肉少女帯
Charset: UTF-8

GET SHIORI/3.0
Sender: materia
ID: OnMusicPlay
Reference0: 元祖高木ブー伝説
Reference1: 筋肉少女帯
Charset: Shift_JIS

ヘッダは以下通りです。

基本的なイベント通知

Charset

リクエスト本体と基本的なヘッダ (DBCS が必要ないヘッダ) は ASCII コードのみで構成されます。

Sender / Script 等 ASCII コードだけでは実用にならないヘッダ内の文字列には以下のキャラクターセットおよびエンコードが使用できます。

これらは明示的に指定しなくてはなりません。IANA に登録されているものを記述するのが妥当です。

指定は以下のようにして行います。

NOTIFY SSTP/1.1
Sender: カードキャプター
Event: OnRelease
Script: ¥0¥s[0]汝のあるべき姿に戻れ。¥e
Option: nodescript,notranslate
Charset: UTF-8

このように記述すると Sender および Script ヘッダは UTF-8 として解釈され，MATERIAmainsystem 到着時点で内部コード（環境依存コード）に変換されます。

Charset に ASCII を指定した場合，送信された文字列はいかなる変換も行われません。

Locale

Charset ヘッダを補足する。ISO 639 (参考 :Wikipedia) の非省略形を指定する ? 省略した場合は Japanese となる。

SSP 拡張。

Unicode / UTF-8 では似た字形の漢字が 1 つのコードに割り当てられているものがあるので，中国語 / 日本語 / 韓国語を指定することでより適した字形を表示することが可能となります。(と，いうように使うヘッダだと思います)

Event

Event は Shiori がイベントの種類を判断する際に使用されます。命名規則は特にありませんが，簡潔かつユニークなネーミングを心がけて下さい。(参考: 伺か - 作業記録文書)

Reference* にはイベントを正しく解釈する上で必要な背景情報を記入します。例えば上記の例では音楽再生開始イベント OnMusicPlay に曲名とアーティスト名が参照情報として与えられています。このような配慮を行うことで Shiori はより的確な反応を返すことができます。

Sender

Sender は SSTP を送信したプログラムの名称を指定します。アプリケーション名ではなく，そのアプリケーション上で動作しているキャラクタ名を指定する場合もあります。

保険反応付きイベント通知

Script

NOTIFY SSTP/1.1
Sender: カードキャプター
Event: OnRelease
Reference0: ウィンディ
Script: ¥0¥s[0]汝のあるべき姿に戻れ。¥e
Charset: Shift_JIS

Shiori が当該イベントを解釈しなかったとき（無反応だったとき）は Script ヘッダで識別されるスクリプトが表示されます。

ただし，セキュリティのためスクリプトで使用できるタグには制限があります。

Option

NOTIFY SSTP/1.1
Sender: カードキャプター
Event: OnRelease
Reference0: ウィンディ
Script: ¥0¥s[0]汝のあるべき姿に戻れ。¥e
Option: nodescript,notranslate
Charset: Shift_JIS

Option ヘッダで以下のコマンドが使用できます。

, (カンマ) で区切ることで，複数のコマンドを指定することが出来ます。

notranslate は，IfGhost により既に対象ゴーストに最適化されたスクリプトを送信する際に，トランスレートによりセリフが不自然になるのを防ぐため，などに使用します。

IfGhost

保険反応付きイベント通知において，固有のゴーストに最適化されたシナリオを送信するためには次のように記述します。

NOTIFY SSTP/1.1
Sender: カードキャプター
Event: OnRelease
IfGhost: せりこ,まるちい
Script: ¥0¥s[0]封印解除。¥e
IfGhost: さくら,ケロ
Script: ¥0¥s[0]汝のあるべき姿に戻れ。¥e
Charset: Shift_JIS

IfGhost は sakura.name,kero.name の形式で指定し，1つ目が本体側，2つ目がうにゅう側の名前です。これは大文字小文字などを含め完全に一致する必要があります。

SSTPではヘッダは順不同となっていますが，IfGhost とその対象ゴーストで使用する Script は連続した2行に記述してください。また，IfGhost で指定されなかったゴーストは最初に出現する Script を使用します。

上記の例では，ゴーストがせりこだった場合は「封印解除。」，さくらだった場合は「汝のあるべき姿に戻れ。」と発言します。せりこでもさくらでもなかった場合，せりこのセリフを喋ります。

CROW，ninix-aya では IfGhost ヘッダに現在稼働中のゴーストは無いが，インストール済みのゴーストがある場合，自動的にゴーストが切り替わって発言します。

選択肢インターフェース

保険反応付きイベント通知において，選択肢のあるスクリプトを送信するには次のように記述する。

NOTIFY SSTP/1.1
Sender: カードキャプター
Script: ¥0¥s[0]どんな感じ？¥n¥n¥q[まあまあ,#temp0]¥n¥q[今ひとつ,#temp1]
Entry: #temp0,¥0¥s[0]ふーん。¥e
Entry: #temp1,¥0¥s[0]酒に逃げるなヨ！¥e
Charset: Shift_JIS

Entry ヘッダで送られたエントリはそのセッション 1 回きりの一時的なスクリプトとしてサーバに格納されます。一時スクリプトはセッション中完全なエントリとして機能しますが，セッション終了次第全て破棄されます。権限は SSTP と同レベルで危険なタグは通りません。

Script の ¥q タグ 及び Entry ヘッダで使用するエントリ ID は # で始まらなければなりません。

上記の例ではバルーンに 2 分岐の選択肢を表示し，「まあまあ」を選ぶとバルーンで「ふーん」というセリフが発言され，同時にクライアントには「まあまあ」という戻り値が返ります。

SSTP/1.1 200 OK[CRLF]
[CRLF]
まあまあ[CRLF]
[CRLF]

サーバ上で選択肢が選択されるまで双方の処理は基本的にブロックされます。このケースでは SSTP の 2 秒ルールは適用されず，返値が得られるまでサーバは応答を返しません。正しく選択肢が選ばれた場合は 200 および返値が，タイムアウトした場合は 204 が，SSTP ブレイクを受けた場合は 210 が返ります。

IfGhost 及び Entry を使うことによって次のようなことも可能です。

NOTIFY SSTP/1.1
Sender: カードキャプター
Event: OnRelease
IfGhost: せりこ,まるちい
Script: ¥0¥s[0]せりこだー。¥w8¥n¥n¥j[#mainblock]
IfGhost: さくら,ケロ
Script: ¥0¥s[0]さくらだー。¥w8¥n¥n¥j[#mainblock]
Entry: #mainblock,¥s[7]寝言は寝てから言えっ！¥w8¥1¥s[10]落ち着けっ！¥e
Charset: Shift_JIS

postmessage

Direct SSTP で行う保険反応付きイベント通知において，クライアントが SSTP サーバの動作状況を精細に把握するための仕様です。Windowsという固有のOSに傾倒した内容となっており，やや異色な仕様です。

NOTIFY SSTP/1.1
Sender: カードキャプター
HWnd: 1024
Event: OnRelease
Script: ¥0¥s[0]¥m[1255,0,0]星の力を秘めし鍵よ¥w4真の姿を我の前に示せ¥m[1255,0,1]¥e
Charset: Shift_JIS

HWnd ヘッダは以降の ¥m タグのメッセージ送付を受けるウインドウハンドルです。適切なウインドウプロシージャを持つハンドルを指定して下さい。

上記の例ではセリフが表示し始めると同時に postmessage(1024,1255,0,0) が実行され，「我の前に示せ」と表示が終了した瞬間に postmessage(1024,1255,0,1) が実行されます。

Marker

Marker は Script によるセリフを喋る際に SSTP マーカーと共に表示される文字列を置き換えるためのヘッダです。

(おそらく) Option ヘッダで nodescript を指定している場合，Marker ヘッダは無効になります。

SSP 拡張 (1.10.00 Pre6 で追加) 。

SEND/1.4

SEND リクエストを外部アプリケーションが使うことで「伺か」を「表現体」として使用することが可能となります。ただし，ゴーストの人格を無視した発言をさせることが多いため NOTIFY リクエストが推奨されます。

ヘッダは以下の通りです。

Owned SSTP

特殊なヘッダ ID が付与された SEND リクエストは Owned SSTP となり Script が無限権限で実行される。特徴は以下の通り。

• 全コマンド使用可能
• タイムクリティカルセクションを無視（Conflict しない）
• SSTP サービスが無効になっていても届く

ID は捏造されにくい文字列であり Shiori ロード時に NOTIFY によって Shiori へ通知されます。

SEND SSTP/1.4
ID: bdf45602c68c26e4e8ed3de82225aaba
Sender: test
Script: ¥![vanishbymyself]

上記のように送信されたスクリプトは Shiori からのレスポンススクリプトと同様の無限権限で実行されます。

SAORI 等が SHIORI を介さず SEND SSTP により Script を実行する，Shiori の自立動作による発言(ランダムトーク)を OnSecondChange 等の戻り値ではなく，SEND リクエストで行う，などの用途が考えられます。

EXECUTE/1.3

EXECUTE リクエストは（主に出力を伴わない）汎用的なコマンド実行を目的としたリクエストです。

EXECUTE SSTP/1.3
Sender: サンプルプログラム
Command: GetName
Charset: Shift_JIS

この2つは必須です。どちらが欠けても Bad Request になります。

Command ヘッダで使用できるコマンドは以下の通りです。

サーバはステータスコードと，必要があれば追加データを返します。追加データは伺かの場合SJISで返ります。

実装されていないコマンドを出すと Not Implemented が返ります。

GetName

現在動作中のキャラクタの名前 (sakura.name 又は sakura.name,kero.name) が返ります。

クライアントはこのデータを取得することで，現在サーバが「誰」なのか知ることができ，キャラクタによってセリフの内容を変えたり，あるいは送信を中止したりすることができます。

公式の仕様にはキャラクタの名前取得としか書かれていないため，返す値が SSTP サーバにより異なります。

Materia では sakura.name です ?

GetNames

インストールされている全キャラクタの本体側の名前 (sakura.name) のリストが返ります。

クライアントはこのデータを取得することで，サーバに「誰」が存在するかを知ることができ，キャラクタによってセリフの内容を変えたり，あるいは送信を中止したりすることができます。

ninix-aya 拡張

GetVersion

SSTP サーバはバージョンを識別できる文字列を返します。それは例えば以下のようなものです。

period 583

GetCollision

SSTP EXECUTE GetCollision拡張 を参照してください。

ExtractArchive

アーカイブファイルの解凍を指示。

Reference0	アーカイブのファイル名 (必須)
Reference1	解凍先フォルダ (必須)
Reference2	解凍終了時のメッセージ通知 (MSG,WPARAM,LPARAM)

Ref2 がない場合は，解凍終了で SSTP レスポンスが返ります。Ref2 がある場合は，解凍準備完了で SSTP レスポンスが返り，解凍終了でメッセージがポストされます。

SetCookie[key,value], GetCookie[key]

適切な引数を設定して SetCookie を送るとそのデータがサーバに格納されます。格納したデータは GetCookie で引き出すことができます。

格納されたデータは書いたクライアント本人にしか読み出せないことに注意して下さい。例えば A というクライアントがサーバに格納した visitcount というデータを B というクライアントが読み出そうとしても失敗します。これはセキュリティ保持と変数名バッティング回避の2つの目的があります。

Quiet, Restore

Quiet を指示するとサーバはしばらくの間自分の意志で喋らなくなります。つまり，連続した SSTP を送ることが分かっている場合（人格が大きく SSTP クライアント側に移る場合），最初に Quiet を指示することでその連続的発言を邪魔されないようにできます。

Quiet セッションは Restore が指示されるか，あるいはリクエストなしで約 16 秒間放置することで解除されます。

サーバに Quiet を指示できるのは，現段階ではサーバと同一の IP アドレスを持つクライアントだけです。

CheckQueue

クライアントが送信した SEND SSTP の内，バルーンへの表示が終了していないリクエストの数を返す。

CheckQueue を送信したクライアントのリクエストのみを数え，別のクライアントが行ったリクエストは数えない。

主に SSTP Bottleクライアント用。

ninix-aya 拡張

SetProperty[key,value], GetProperty[key]

SSTP サーバが保持するシステム変数やゴーストが持つ各種変数へアクセスします。

詳しくはCROW - テスト項目資料，ぽな@ばぐとら/仕様妄想メモ/プロパティシステムを参照。

CROW 拡張

COMMUNICATE/1.1

COMMUNICATE リクエストは Shiori に質問や同意を求める文章などを送り，それに答えさせ，必要があれば返答を受け取るリクエストです。主にユーザとの対話や別の人工知能との会話での使用を想定しています。

このリクエストは現段階ではローカルマシンからのリクエストに限ります（外から来たものは蹴ります）。

COMMUNICATE SSTP/1.1
Sender: カードキャプター
Sentence: 今日は寒いなー。
Option: substitute
Charset: Shift_JIS

GET SHIORI/3.0
Sender: materia
ID: OnCommunicate
Reference0: カードキャプター
Reference1: 今日は寒いなー。
Charset: Shift_JIS

Sender と Sentence は必須です。どちらが欠けても Bad Request になります。

ユーザが文章を送る場合は Sender ヘッダは user または User と指定してください。

Option ヘッダで使用できるコマンドは以下の通りです。

substitute オプションを使用すると Sentence 文字列を kero (¥1側キャラクタ) がセリフとして発言します。この構造により，セリフの発言能力がないクライアントが COMMUNICATE リクエストを利用する際，kero をセリフの代理発言者として利用することができます。

この仕様では Shiori から返答としての発言を得るだけであり，その返答は送り手にデータとしては戻ってきません。 ユーザとの対話ではこの仕様で十分ですが，Shiori 間で対話をさせることができません。 Shiori 同士での対話を可能とするため COMMUNICATE/1.2 へと拡張されました。

COMMUNICATE/1.2

COMMUNICATE/1.2 は 2つの AI 間での対話を行うための仕様です。COMMUNICATE/1.1 との違いは，返答が話しかけた側へ COMMUNICATE/1.2 で送られることです。このリクエストは SSTP サーバでかつ SSTP クライアントでもあるプログラム（例えば MATERIAmainsystem）以外が行ってはなりません。

このリクエストは現段階ではローカルマシンからのリクエストに限ります。

COMMUNICATE SSTP/1.2
Sender: 双葉
HWnd: 1405
Sentence: ¥0¥s[0]どうも。¥e
Surface: 0,10
Reference0: N/A
Charset: Shift_JIS

Sender，Sentence と Port 又は HWnd が必須です。

MATERIAmainsystem は COMMUNICATE/1.2 リクエストに対する Shiori の返答をバルーンに表示すると同時に Port もしくは HWnd ヘッダから得られる送信元サーバ（話しかけたサーバ）に COMMUNICATE/1.2 により送り返します。この構造により 2サーバは事実上の会話を行います。

SHIORI/3.0 での会話は，Shiori が，任意の SHIORI リクエストに対し Reference0 ヘッダに送信先ゴースト名のあるレスポンスを返すことでコミュニケートが開始します。以降，OnCommunicate に対し，Reference0 付きのレスポンスを返し続ける限り会話が継続します。

GIVE/1.1 - deprecated -

このリクエストは非推奨リクエストです。ほかのリクエストを使ってください。

GIVEリクエストは MATERIAmainsystem にデータを与え，それを処理させたり，あるいは反応させたりするリクエストです。SHIORI が本体からパージされた現在，本体にデータを送る意味はありません。

このリクエストは現段階ではローカルマシンからのリクエストに限ります（外から来たものは蹴ります）。

GIVE SSTP/1.1
Sender: カードキャプター
Document: 闇の力を秘めし鍵よ真の姿を我の前に示せレリーズ。汝のあるべき姿に戻れクロウカード。
Charset: Shift_JIS

Sender といずれかのソースデータ，この2つは必須です。どちらが欠けても Bad Request になります。ソースデータが複数ある場合はいずれか1つが優先されます。

サーバはステータスコードのみを返します。

Document は受信しますが (おそらく) 内部では使用されていません。

Songname は救済処置として SHIORIリクエスト ID: OnMusicPlay で Shiori に送られます。

INSTALL/1.0 - SSP 拡張 -

INSTALL SSTP/1.0
Sender: Angeliclayer
Path: C:\temp\misakichi.nar

通常，NAR ファイルのインストールは，ファイル / URI をゴーストへ DnD することにより行います。INSTALL SSTP はユーザの DnD の代わりに，外部アプリケーションが本体にインストールを通知するために使用します。

SSP 拡張。詳しくは SSTP関連の資料 - とらぶる☆ばぐとらっく を参照。

レギュレーション

通信はコネクト終了後サーバ側のローカルタイムで最長でも 2 秒以内に終了する必要があります。2 秒で終わらなかった場合は Request Timeout が返り強制切断されます。

リクエストヘッダの最大長は 2KB=2048 バイト（ローカルマシンからは 16KB=16384 バイト）に制限されています。これより長いヘッダを送ると Bad Request となり直ちに切断されます。

データベース

• 非公式 伺か シェル仕様書
• 非公式 伺か SERIKO 仕様書
• 非公式 伺か MAYUNA 仕様書
• 非公式 伺か element 仕様書
• 非公式 伺か インストーラ仕様書
• 非公式 伺か SSTP/1.x プロトコル仕様書
• 伺かシステム用語集
• タダで始める C/C++ プログラミング
• VC++.NET メモ #01
• Virtuaroid
• まんがサイエンス 新旧比較