SHIORI/3.0¶

参考：SHIORI/3.0（外部サイト） SHIORI/2.x（外部サイト）

実装対応状況の検知¶

拡張ヘッダの実装対応状況については、ID: capabilityでSHIORI実行の初期に通知される。

request¶

サンプル¶

GET SHIORI/3.0
Charset: UTF-8
Sender: SSP
SenderType: internal,raise
SecurityLevel: local
Status: choosing,balloon(0=0)
ID: OnFirstBoot
BaseID: OnBoot
Reference0: 1

※改行コードはCR+LF。
※最後は空行（前行の終端と合わせて(CR+LF)x2）で終わること。

メソッド:
- GET: レスポンスのValueヘッダでなにかしらを返すことを前提としているメソッド。
- NOTIFY: 何も値を返さないことを前提としているメソッド。レスポンスのValueヘッダは無視される。
  主に何かしらのモードの制約で「喋れない」状態の時や、起動直後の状態通知イベントに使用される。
  同じID(イベント名)でGET/NOTIFYの両方とも使われる場合があるので注意。

Charset: 文字コード。最初の行、または少なくとも文字コードがASCII範囲以外の行の前が望ましい。

Sender: イベント送信元。

SenderType [SSP 2.5.05～拡張]: イベント送信元の属性。下記の通り。複数ある場合はカンマでつなげたもの。
ID: OnTranslateについては、トランスレート元のイベントの属性を引き継ぐ。
- internal: アプリケーション内部からのイベント。
- external: アプリケーション外部からのイベント。
- sakuraapi: Sakura APIによって起こされたイベント。
- embed: \![embed]タグによって起こされたイベント。
- raise: \![raise]タグによって起こされたイベント。
- property: プロパティシステムの参照命令の結果起こされたイベント。
- plugin: プラグインによって起こされたイベント。
- sstp: SSTPによって起こされたイベント。
- communicate: コミュニケート仕様によって起こされたイベント。

SecurityLevel: スクリプト実行時のセキュリティレベル。下記のいずれか。
ID: OnTranslateについては、トランスレート元のイベントの属性を引き継ぐ。
できるだけ最初のほうの行で通知される。少なくともIDヘッダより前に現れる。
- local: 実行中の端末内からの通知。
- external: 実行中端末の外部からの通知。
externalの場合は実行中マシンの外部からの通知なので、セキュリティ的に取り扱いに注意を要する。
SenderTypeのinternal/externalとは別の概念であり、アプリケーション外から発生したイベントであっても、安全とみなして良いものはlocal判定となるので、SenderTypeがexternalでもSecurityLevelがlocalとなる場合がある。

SecurityOrigin [SSP拡張]: 送信元サーバを示すURL風の文字列。以下の形式となる。HTTPヘッダのOriginと考え方は同じ。
SecurityOrigin: null
SecurityOrigin: <scheme>://<hostname>
SecurityOrigin: <scheme>://<hostname>:<port>
scheme は通常、http,https,sstpのいずれか。hostnameは送信元サーバ名かIP。portは返信受付可能なポート。
SSTPなどでヘッダが指定されていない、そもそも送信元の概念がないなど、情報なしの場合はnullとなる。
SSTP仕様のSecurityOriginも参照すること。

Status [SSP拡張]: ゴーストの実行状態。下記の通り。複数ある場合はカンマでつなげたもの。
- talking: 喋っている途中
- choosing: 選択肢表示中
- minimizing: 最小化中
- induction: \![enter,inductionmode]中
- passive: \![enter,passivemode]中
- timecritical: タイムクリティカルセクション(\t)中
- nouserbreak: \![enter,nouserbreak]中
- online: ネットワーク通信中
- opening(種類): 入力ボックス等が開いている。
  複数種類が開いている場合は/区切りで列挙される。
  "dialog"はファイル選択・カラーピッカー等。
  例：opening(communicate/input/teach/dialog)
- balloon(ID群): バルーンが表示状態。
  キャラクターID=バルーンID の形式で列挙される。
  複数開いている場合は/区切りで列挙される。
  例：balloon(0=2/1=0) で、\0が大きいバルーン、\1が通常のバルーンを表示中の意。

ID: イベント名、またはテキストリソースの識別子。

BaseID [SSP拡張]: 互換可能な基本のイベント名。
例：OnFirstBootはOnBootと互換で、かつOnFirstBootはOnBootの亜種なので、OnFirstBootのBaseIDにはOnBootが入る。

Reference*: イベントに付随する追加情報群。Referenceの後には数字が入る。入れられる行数は制限なし（メモリが許す限り）

X-SSTP-PassThru-(任意の文字列) [SSP 2.5.05～拡張]: SSTPからイベント通知が来た場合に限り、SSTPのリクエストヘッダ内で"X-SSTP-PassThru-"ではじまるものがそのまま通知される。
SSTP以外の時は追加されない。

response¶

サンプル¶

SHIORI/3.0 200 OK
Charset: UTF-8
Sender: AYA
Value: \1\s[10]\0\s[0]\e

※改行コードはCR+LF。
※最後は空行（前行の終端と合わせて(CR+LF)x2）で終わること。

ステータスコード: HTTPと同じく、200番台が成功、ほかはなにかしらの失敗（エラー）を示す。
現在主に使用されているのは下記の通り。
- 200: 200 OK
  成功、返り値(Value)あり。
- 204: 204 No Content
  成功、返り値なし。
- 311: 311 Not Enough
  ID: OnTeach (SHIORI/2系のTEACHメソッド)において、さらなる追加情報を必要とすることを示す。
  入力ボックスを再度開いてユーザーに問い合わせ、入力完了後に入力文字列を含むReferenceを追加する。
- 312: 312 Advice
  ID: OnTeach (SHIORI/2系のTEACHメソッド)において、直近で入力された文字列が解釈不能のため破棄すべきことを示す。
  一番最後のReferenceを破棄し、入力ボックスを再度開いてユーザーに問い合わせ、入力完了後に入力文字列を含むReferenceを追加する。
- 400: 400 Bad Request
  リクエスト文字列が解釈不能だった。
- 500: 500 Internal Server Error
  SHIORI内部でなにかしらのエラーが起き、レスポンスを返せなかった。

Charset: 文字コード。最初の行、または少なくとも文字コードがASCII範囲以外の行の前が望ましい。

Sender: 送り主。通常はSHIORIの名前。

Value: 喋りたいスクリプト。

ValueNotify [SSP拡張 2.5.35]: [実験的機能]
リクエストメソッドがNOTIFYの場合でもSakuraScriptを実行するための拡張機能。
このヘッダでSakuraScriptを返すと、即時実行される。GETの場合はValueヘッダのスクリプトを実行する前に実行される。
実行できるタグは極めて限られ、他のタグやその他文字列は全て無視される。
~~メソッドがNOTIFYでない時や、Valueヘッダがすでにある時は無視される。~~ 2.6.76で制限廃止
現在実行できるタグは以下の通り：
- \![sound]
- \![set,trayicon]
- \![set,trayballoon]
- \![raise]
- \![raiseother]
- \![raiseplugin]
- \![timerraiseother]
- \![timerraiseplugin]
- \![notify]
- \![notifyother]
- \![notifyplugin]
- \![get,property] ＋2.6.82
- \![set,property] ＋2.6.82

SecurityLevel [SSP拡張]: 下記のいずれか。
- local: 実行中の端末内からのスクリプト相当のセキュリティレベル。
- external: 実行中の端末の外部からのスクリプト相当のセキュリティレベル。
喋りたいスクリプトのSecurityLevel。externalだと一部のスクリプトがセキュリティ機能により実行不能になる。

Marker [SSP拡張]: バルーンマーカー(バルーン下側の追加情報)に表示したい文字列。

ErrorLevel [SSP拡張]: SHIORI内部で起きたエラーのレベル。下記のいずれか。複数のエラーを表現したい時はバイト値1で区切る。
- info: 情報。エラーではない。
- notice: 通知。エラーとは言い難いものの修正すべき記述など。
- warning: 警告。記述ミスなどがあり、処理は停止していないが対処したほうがいいもの。
- error: 通常のエラー。記述ミスなどで何か処理が停止して再開できない。
- critical: 致命的エラー。errorより酷く、すぐに何かしら対処をしたほうが良いもの。
このヘッダがある場合は、ユーザーになにかしらのエラーが起きたことが通知される。
通知されるレベルはユーザーが設定変更可能。通常はerror以上。
SSPの場合はエラーログに記録され、エラーアイコンが通知領域に出る。

ErrorDescription [SSP拡張]: SHIORI内部で起きたエラーの詳細情報。ErrorLevelがある場合のみ有効。
複数のエラーを表現したい時はバイト値1で区切る。
ErrorLevelとErrorDescriptionの要素数は必ず同じでないといけない。

BalloonOffset [SSP拡張]: バルーンのオフセット値(X,Y)。

Reference0: コミュニケートを送りたい場合、ゴーストの\0側の名前。

Reference1～: コミュニケートの追加情報。
レスポンスのReference1＝SSTP CommunicateのReference0＝受け手のOnCommunicateのReference2
互換性の問題で以上のようにずれてしまうことに注意。

Age [SSP拡張]: コミュニケートの世代数。初回はゼロ。やりとりを重ねるたびに+1。
SSP拡張だが、実質はSHIORI/2.x互換処理。

MarkerSend [SSP拡張]: コミュニケート中に「相手側に」表示したいバルーンマーカー文字列。
SSTPのMarkerヘッダとして送信される。

X-SSTP-PassThru-(任意の文字列) [SSP 2.5.03～拡張]: SSTPからイベント通知が来た場合のレスポンスに限り、このヘッダがSSTPのレスポンスにそのまま追加される。
SSTP以外の時は無視される。
複数のヘッダを指定可能だが、複数返したい場合はヘッダ名を変えること。
（旧ヘッダ名：X-SSTP-Return- は廃止予定）