Susieプラグイン API一覧

戻る

はじめに

プラグインの仕様については、 Susieの部屋 のPlug-in packageに含まれる、spi_api.txtを参照してください。

ここでは、各関数の注意点などを書いておきます。

エラーコード

GetPluginInfo()とIsSupported()以外は、以下のエラーコードを返します。
エラー名は、どなたかのサンプルを参考にしています。

値 エラー名 意味
-1 SPI_NO_FUNCTION その機能はインプリメントされていない
0 SPI_ALL_RIGHT 正常終了
1 SPI_ABORT コールバック関数が非0を返したので展開を中止した
2 SPI_NOT_SUPPORT 未知のフォーマット
3 SPI_OUT_OF_ORDER データが壊れている
4 SPI_NO_MEMORY メモリーが確保出来ない
5 SPI_MEMORY_ERROR メモリーエラー
6 SPI_FILE_READ_ERROR ファイルリードエラー
7 SPI_WINDOW_ERROR 窓が開けない (非公開のエラーコード)
8 SPI_OTHER_ERROR 内部エラー
9 SPI_FILE_WRITE_ERROR 書き込みエラー (非公開のエラーコード)
10 SPI_END_OF_FILE ファイル終端 (非公開のエラーコード)

flagパラメータについて

多くの関数で使われる、flagパラメータには注意してください。
以下のように、ファイル入力かメモリ入力かを切り分けます。 

	if ((flag & 1) == 0)
	{
		// ファイル入力
	}
	else
	{
		// メモリ入力
	}
ファイル入力かメモリ入力かで処理を分けるのが面倒ですので、
ファイルはメモリ上に展開するなどして、処理を統一した方が良いです。
サンプルではファイルマッピングしています。

GetPluginInfo

int GetPluginInfo(int infono, LPSTR buf, int buflen);

infonoに応じた、プラグイン情報の文字列を取得します。
終端文字'\0'は必ず付けましょう。
bufに実際に書き込んだ文字数を返します。
strlenなどの標準関数に倣い、終端文字を含まない文字数を返すべきでしょう。

infono = 2以降は、偶数と奇数番号で一つのセットになります。
複数のファイルタイプに対応させることも可能です。

infono 内容 サンプル
0 Plug-in APIバージョン 画像表示系なら"00IN"
アーカイブ系なら"00AM"
1 Plug-in名、バージョン及び copyright PNG Plug-in version 1.00
(C)Kouji
2, 4, ... 拡張子 *.png
3, 5, ... ファイルタイプ PNGファイル

仕様が明確に書かれてなかったせいか、終端文字を付けなかったり、 終端文字を文字数に含んでいるプラグインも存在します。
プラグインを利用するアプリをつくる場合、注意しましょう。

IsSupported

int IsSupported(LPSTR filename, DWORD dw);

対応したファイルなら非0、未対応なら0を返します。
対応チェックは厳密に行ってください。
いったんOKを返してしまうと、他のプラグインには対応を確認する機会が与えられません。
IsSupported()でOKといっておきながら、GetPicture()で未対応を返すプラグインは最悪です。
（ファイルが壊れている場合は仕方ないですが）

極力、filenameは判断材料に用いないようにしましょう。
拡張子は信用できませんし。

dwの上位2バイトが0の場合、dwはファイルハンドル(HANDLE)です。
dwの上位2バイトが非0の場合、dwはバッファへのポインタで、 バッファサイズが2048以上であることが保障されています。

プラグインを利用するアプリをつくる場合、2KB未満のファイルの扱いに注意してください。
また、MACバイナリはアプリ側で考慮する必要があります。
対応プラグインが見つからない場合、128バイトスキップしてIsSupported()を呼んでみて下さい。

GetPictureInfo

int GetPictureInfo(LPSTR buf, long len, unsigned int flag, struct PictureInfo *lpInfo);

画像ファイルに関する情報を取得します。
内部テキストを取得するときくらいしか使われません。

flagパラメータについては、こちらを参照。

PictureInfo構造体は、アライメントを1バイトにする必要があります。
各コンパイラのオプションや#pragmaで指定してください。
PictureInfo構造体のhInfoメンバは、未使用時0(NULL)にしてください。
Susieが誤動作する可能性があります。

GetPicture

int GetPicture(LPSTR buf, long len, unsigned int flag, HANDLE *pHBInfo, HANDLE *pHBm, FARPROC lpPrgressCallback, long lData);

画像を展開します。

flagパラメータについては、こちらを参照。

pHBInfoにBITMAPINFO構造体、pHBmにピクセルデータをセットします。

lpPrgressCallbackは、Susie側で展開状況を表示するためのコールバック関数です。
NULLでないことを確認してから呼んで下さい。
最近のPCなら、ほとんど一瞬で表示されるので、呼ばなくてもいいかも。

GetPreview

int GetPreview(LPSTR buf, long len, unsigned int flag, HANDLE *pHBInfo, HANDLE *pHBm, FARPROC lpPrgressCallback, long lData);

プレビュー・カタログ表示用画像縮小展開ルーティン。
JPEGのように、縮小画像が高速で展開できるときに実装してください。
実装しない場合は、SPI_NO_FUNCTIONを返してください。

GetPictureとパラメータが全部一緒です。
出力サイズに特に指定がないため、アプリ側でもあまり使い道がないかも。

GetArchiveInfo

int GetArchiveInfo(LPSTR buf, long len, unsigned int flag, HLOCAL *lphInf);

アーカイブ内のすべてのファイル情報を取得する。

flagパラメータについては、こちらを参照。

lphInfにはファイル情報の入ったハンドルへのポインタを返します。 ややこしい部分ですが、具体的には以下のようにします。 

    	HANDLE h = ::LocalAlloc(LHND, size);	// ファイル情報のメモリ確保
    	*lphInf = h;	// ハンドルへのポインタを返す

プラグインを利用するアプリをつくる場合、あらかじめ、*lphInf = NULL としておき、 返ってきた*lphInfがNULLになっていないかチェックすることを推奨します。 たまに、OKを返しておきながら、*lphInfがNULLになっているプラグインがあります。

GetFileInfo

int GetFileInfo(LPSTR buf, long len, LPSTR filename, unsigned int flag, fileInfo *lpInfo);

filenameで指定したファイルの情報を取得する。

flagによる入力形式の判定はこちらを参照。 また、flagによってファイル名の比較方法を指定します。 

	if ((flag & 0x80) == 0)
	{
		// ファイル名の大文字小文字を区別する
		// lstrcmp, strcmpなどで比較
	}
	else
	{
		// ファイル名の大文字小文字を同一視する
		// lstrcmpi, _stricmpなどで比較
	}

GetFileInfo()はあんまり使われません。Susie自身も使いません。 そのためか、GetFileInfo()の動作確認をしていないプラグインがよくあります。 GetFileInfo()を使うアプリもあるので、ちゃんと実装して動作確認してください。

GetFile

int GetFile(LPSTR src, long len, LPSTR dest, unsigned int flag, FARPROC prgressCallback, long lData);

アーカイブ内のファイルを取得する。

GetFile()は各パラメータの内容が非常に複雑です。 入力形式の判定はこちらを参照。

入力形式によって入力パラメータは以下のように変化します。

入力形式 src len
ファイル入力 ファイル名 fileInfoのposition
メモリ入力 ファイルイメージへの先頭のポインタ + position アーカイブファイルのサイズ - position

出力先は以下のように判定します。 

	if ((flag & 0x0100) == 0)
	{
		// ファイル出力
	}
	else
	{
		// メモリ出力
	}
出力パラメータは以下のように変化します。

出力先 dest
ファイル出力 出力ディレクトリ(書庫内の相対パスは無視する)
メモリ出力 ファイルの入ったLOCALメモリハンドルを受け取る変数へのポインタ。 
    // 具体例
    HLOCAL* phMem = (HLOCAL*)dest;
    *phMem = ::LocalAlloc(LHND, filesize);

アーカイブによっては、メモリ入力の実装が難しい場合があります。 その場合は、SPI_NO_FUNCTIONを返しましょう。

メモリ入力やファイル出力は実装していないプラグインも多いです。 プラグインを利用するアプリをつくる場合、以下のようにすることを推奨します。

  1. メモリ上のファイルは、テンポラリファイルに出力し、ファイル入力でGetFile()に渡す
  2. ファイル出力する場合、いったんメモリ出力でGetFile()を呼び出し、アプリ側でファイル出力

lpPrgressCallbackは、Susie側で展開状況を表示するためのコールバック関数です。
NULLでないことを確認してから呼んで下さい。

ConfigurationDlg

int ConfigurationDlg(HWND parent,int fnc);

プラグインの設定ダイアログを表示します。
この関数をexportすると、Susieのプラグイン設定ボタンが有効になります。
不要な場合は、exportしない（実装しない）方がいいです。

設定データは、レジストリに持つことになります。
ホストアプリケーションがインポートライブラリを使ってプラグインをリンクした場合、 最初のDllMain()呼び出しでのレジストリ操作は失敗します。
Advapi32.dllがロードされていないためでしょう。
SusieなどほとんどのアプリはLoadLibrary()でリンクするため問題ありませんが、注意してください。

設定ダイアログはDialogBox()やDialogBoxParam()で実装することになるでしょう。
ダイアログリソースの扱いについては、こちらを参照してください。

この関数だけは、Window GUIの知識が必要なので、
まったく経験のない方はちょっと戸惑うかもしれません。 サンプルや適当なサイトを参考にしてみてください。

戻る inserted by FC2 system