SAORI/1.0

SAORIとは？

栞を拡張するバイナリモジュールの仕様を標準化することで、複数の栞で拡張モジュールを共通化する試みです。 関連スレッド：
SHIORIとSAORIのDLL開発者スレ
開発者向け。仕様変更・追加への提案。実装上の疑問などはこちらへ。
こんなさおり／スクリプト作ってください
主として利用者(ex.ゴースト製作者)向け。
リンク

この文書の位置付け

この文書はSHIORI/SAORIの実装者向けです。具体的な各SHIORI/SAORIモジュールにおける使用方法はそれぞれの説明を読んでください。

仕様

Index

basicとuniversal

SAORIの実装はbasicとuniversalの２つに分かれる。 前者はWindows上ではexe形式の実行ファイルとして実装され、後者はDLLとして実装される。

SAORIの実装

universal - DLL形式のSAORI

exportする関数


extern "C" __declspec(dllexport) HGLOBAL __cdecl request(HGLOBAL h, long *len);

呼び出し側は HGLOBAL h にリクエスト文字列を格納したGlobalAlloc(GMEM_FIXED, ...)によって確保した固定メモリ領域のポインタを、 long *len にそのデータサイズを格納した変数へのポインタを格納しrequestを呼び出す。
SAORIモジュールはGlobalFree()によってhの指すメモリ領域を開放する責任がある。 返り値はGlobalAlloc(GMEM_FIXED, ...)によって確保された固定メモリ領域へのポインタである。 SAORIモジュールはこのメモリ領域に後述する書式に従った返答の文字列を、(long *len)の指す変数にそのデータサイズを格納して返す。この返答の領域を開放するのは呼び出し側の責任である。 


extern "C" __declspec(dllexport) BOOL __cdecl load(HGLOBAL h, long len);



extern "C" __declspec(dllexport) BOOL __cdecl unload();

load/unloadはexportしないことも可能である。その場合は動的ロード可能なモジュールだと判断され、呼び出し側は必要に応じてSAORIモジュールをロードし、開放できる。但し、load/unloadのどちらか一方のみexportすることはできない。
Load/unloadがexportされている場合は、ロード後はホストが開放されるタイミングまで開放してはいけない。

データは全て HGLOBAL で引き渡され、long len にはそのデータサイズが格納される。渡されるハンドルの解放は全て渡された側に委ねられており、渡した側では解放を行わない。

loadはDLLのロード時にコールされる。このとき引数としてDLLの存在するフォルダの絶対パスが\で終端された形で渡される。SAORIは必要ならばこれに基づいて自己を初期化するべきである。

unloadはDLLのアンロード時にコールされる。SAORIは必要ならばこのとき終了処理を行う必要がある。

request は栞が処理を要求する場合にコールされる。引数には一定のフォーマット化された文字列が渡され、返り値として、同じくフォーマット化された文字列を返す必要がある。

引数・返り値の形式

引数
(Command Version)[CRLF] (例: EXECUTE SAORI/1.0)
SecurityLevel: (Local|External)[CRLF]
Argument0: Value[CRLF] (例: Argument0: GetMD5)
Argument1: Value[CRLF]
Argument2: Value[CRLF]
	・
	・
	・
Argument[n]: Value[CRLF]
Charset: (Shift_JIS|ISO-2022-JP|EUC-JP|UTF-8)[CRLF]
Sender: (ShioriName)[CRLF]
[CRLF]

返り値

version statuscode statusstring[CRLF] (例: SAORI/1.0 200 OK)
Result: Scalar-Value[CRLF]
Value0: Vector-Value[CRLF]
Value1: Vector-Value[CRLF]
Value2: Vector-Value[CRLF]
	・
	・
	・
Value[n]: Vector-Value[CRLF]
Charset: (Shift_JIS|ISO-2022-JP|EUC-JP|UTF-8)[CRLF]
[CRLF]
各行はCRLFで区切られる。２行目以降は": "で区切られたKey,valueの対。
全て順不同。
コマンドリスト
GET Version
GET Versionはload後に呼ばれる。 SAORIからの返答は、先頭に"SAORI/1.0"という9バイトの文字列を含まなければならない。 呼び出し側はこの返り値に"SAORI/1.0"を発見できなかった場合、該当モジュールをSAORIとして扱ってはならない。
EXECUTE
EXECUTEはSAORIに処理を行わせるためのコマンドである。

エラー処理

SAORIを呼び出す側は返り値のステータスコードによって適切なエラー処理を行う必要がある。
ステータスコード
200 OK - 正常終了
SAORIモジュールの呼び出しは正常に終了した。
204 No Content - 返り値なし
処理は正常に行われたが、結果として返す値はなかった。
400 Bad Request - 呼び出しの不備
引数の数、内容の不一致。
リクエストの内容が解釈不能
など。
500 Internal Server Error - SAORI側エラー
SAORIモジュール側でなんらかのエラーが発生した。

SAORIの寿命

原則としてUniversal形式のSAORIモジュールは栞のload時に読み込まれ、unload時に破棄される。
例外として、load/unloadをexportしないことによって動的なloadを許可することができる。 この場合、栞は使用頻度やメモリ消費量などによる判断でSAORIモジュールの動的なロード・開放を行うことができる。

返り値

単数と複数
SAORIの返すべき値は原則として単一の文字列だが、必要に応じて複数の文字列を返すこともできる。ただし、複数の返り値を処理できるかは栞側の対応次第なので注意すべきである。
単数の返り値
Result: content
複数の返り値
Value[n]: content
SAORIモジュールは必要に応じて複数の返り値を返すこともできる。 但し、複数の返り値をサポートしない栞との互換性のために、 複数の値を返す場合でも、単数形式での返り値は必須である。
返り値はValue0からValue[n]までの任意の数を返すことができ、上限は特にない。

basic - EXE形式による実装

EXE形式でSAORIを実装する場合、Proxy DLLを経由する。よって栞側からみればuniversal形式のSAORIモジュールと等価であり、呼び出し手順に差は無い。

引数

basic形式のSAORIモジュールは引数をコマンドライン引数として呼び出される。

返り値

EXE形式のSAORIモジュールは返り値は標準出力に出力する。
返り値はUniversal形式のResultに相当する単一の文字列である。

SAORIの定義ファイル。

SAORIを呼び出す栞に情報を渡すために、一定の書式のテキストファイルが用意される。
書式は呼び出し側の栞の内部構造に依存するため、特に標準は定めない。

SAORIのファイル配置 

home
 +-ghost
    +-[Name]
        +-ghost
           +-master
              +-shiori.dll
              +-SAORI.txt
              +-md5.dll
              +-proxy.dll
              +-proxy.ini
              +-serch.exe
              +-update
              |  +-update.exe
              |  +-tmp
              |  |  +-tmp.dat
              |  +-work.lst
              +-pinball
                 +-pinball.dll
                 +-pinball.ini
SAORIモジュールは適切な定義ファイルの記述を行うことで、栞が存在するフォルダ以下の任意の場所に配置することができ、独自のフォルダを持つことも可能である。
特に、独自の設定ファイルや作業ファイル等を持つSAORIモジュールはフォルダによって他のSAORIモジュールや栞の使用するファイルと隔離することが推奨される。

履歴

2012-03-13
リンク修整。
2004-11-04
関連リンク等。
2004-06-06
関連リンク等。
2002-03-23
RC4。　Get Versionの返すべき値に関する記述の変更。
2002-03-13
RC3。　exportする関数名の訂正。CSSの修正。履歴へのリンク修正。
2002-02-22
RC2。　記述の訂正。
2002-02-16
RC1。
2002-01-30
名称仮決定。エラーの取り扱い。
2002-01-29
名称案。
ファイル配置。
2002-01-28-02
名称案。
返り値。
関数の形式。
ファイル配置。
2002-01-28-01
公開。

SDN(sdn@boreas.dti.ne.jp)