SAORI/0.0 (RC1/20020216-01)

SAORIとは？

栞に対するバイナリ拡張の形式を標準化することで、機能拡張に対する栞開発者の負荷を軽減すると同時に、ゴーストデベロッパが、使用している栞に要求する機能が無いことを理由に、思いついたネタを諦めたり、もしくはそのためだけに栞を乗り換える必要をなくすためのものです。
関連スレッド：栞を考えるスレ(現在、議論中)

basicとuniversal

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

SAORIの実装

universal - DLL形式のSAORI

exportすべき関数


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

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

getversionはSAORIのロード時、loadより前にコールされる。SAORI DLLはSAORI/1.0という 9バイトの文字列を返さなければならない。これが正常に行われなかった場合、SAORI DLLはロードされない。

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

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

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

引数・返り値の形式

(Command Version)[CRLF] (例: EXECUTE SAORI/1.0)
SecurityLevel: (Local|External)[CRLF]
Argument[0]: Value[CRLF] (例: Argument0: GetMD5)
	・
	・
	・
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]
Value[0]: Vector-Value[CRLF]
	・
	・
	・
Value[n]: Vector-Value[CRLF]
Charset: (Shift_JIS|ISO-2022-JP|EUC-JP|UTF-8)[CRLF]
[CRLF]
各行はCRLFで区切られる。２行目以降は": "で区切られたKey,valueの対。

エラー処理

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モジュールや栞の使用するファイルと隔離することが推奨される。

履歴

2002-02-16
RC1。
2002-01-30
名称仮決定。エラーの取り扱い。
2002-01-29
名称案。
ファイル配置。
2002-01-28-02
名称案。
返り値。
関数の形式。
ファイル配置。
2002-01-28-01
公開。

SDN(sdn@boreas.dti.ne.jp