TORO's Data Library(Susie Plug-in 仕様)

Susie 32bit / 64bit Plug-in の仕様(2024-9-28版)

拙作 Susie 32bit / 64bit Plug-in の仕様です。

拙作 Susie 64bit Plug-inは、Susie 32bit Plug-in 仕様 rev5 を元に拡張した独自仕様です。
本仕様は API の 64bit 化に加えて、Susie 32bit Plug-in 仕様 rev5 では記載されていなかった動作の言及や、曖昧な定義の厳格化をおこなっています。

Susie 32bit Plug-in 仕様 rev5 は、Susie 32bit Plug-in の本家となる竹村嘉人 (たけちん)氏のサイト (http://www.digitalpad.co.jp/~takechin/) の Plug-in package ver0.08 に同梱されています。

Plug-in の拡張子
Plug-in の種類
64bit API の概要
API 一覧
エラーコード
bitmap 仕様
その他
テスト用プログラム
参考資料

Homeへ戻る

Plug-in の拡張子

Susie Plug-in として以下の拡張子が決められています。.spi と .PLG が本家仕様です。 .sph, .spha は独自仕様です。

.spi   Susie 32bit Plug-in
.sph   Susie 64bit(x64) Plug-in
.spha  Susie 64bit(ARM64) Plug-in
.PLG   Susie 16bit Plug-in

Plug-in の種類

Susie Plug-in は機能に合わせて２種類あります。

Import filter. 画像展開プラグイン用API
画像ファイルをBITMAPに展開するプラグインです。
ファイル名は "if..." と頭に "if" をつけることが一般的です。
GetPluginInfo の Plug-in APIバージョンは "00IN" になります。
Export filter. アーカイブ展開プラグイン用API
書庫ファイル内のファイルの一覧を取得したり、指定した１つのファイルを展開したりするプラグインです。
ファイル名は "ax..." と頭に "ax" をつけることが一般的です。
GetPluginInfo の Plug-in APIバージョンは "00AM" になります。

64bit API の概要

定義が 32bit / 64bit で共用できるように LONG_PTR 等を使用しています。
64bit 版の構造体はアラインメント合わせを行っているため、要素のアラインメントずれに注意が必要です。
本家仕様では引数に使用していない const を使用しています。
メモリハンドルは明瞭化のため、HANDLE から HLOCAL に変えています。尚、HLOCAL は HANDLE の typedef です。
API 名末尾に「W」が付いているものは UNICODE 版です。
UNICODE 版 API は全てオプションです。
GetArchiveInfo を使ったときは、GetFile / GetFileInfo を使用し、
GetArchiveInfoW を使ったときは、GetFileW / GetFileInfoW を使用する必要があります。
上記以外の UNICODE 版は ANSI 版と混在使用できます。
IsSupported は仕様としてファイルハンドル指定ができますが、既存のファイルハンドル指定アプリケーションのための互換用仕様です。
新規に使用しないでください。また、使用している場合はバッファ指定に置き換えることをおすすめします。
以前の 32bit Windows ではファイルハンドルが 16bit Windows との互換性のために 16bit に納まっていましたが、現在は 16bit を超えるようになり、誤動作するためです。

API 一覧

[IF][AX] GetPluginInfo, GetPluginInfoW
[IF][AX] IsSupported, IsSupportedW
[IF][AX][option] ConfigurationDlg
[IF] GetPictureInfo, GetPictureInfoW
[IF] GetPicture, GetPictureW
[IF][option] GetPreview, GetPreviewW
[AX] GetArchiveInfo, GetArchiveInfoW
[AX] GetFile, GetFileW
[AX] GetFileInfo, GetFileInfoW
[IN][独自, option]CreatePicture, CreatePictureW

※ 一覧の符号説明
[IF] Import filter. 画像展開プラグイン用API
[AX] Export filter. アーカイブ展開プラグイン用API
[option] オプションAPI。APIが存在しない場合がある

※ API のパラメータ欄の符号説明
[in] 入力。プラグイン側で変更禁止
[out] 出力。プラグイン側で変更される

※ API の実装欄の符号説明
[IF] Import filter. 画像展開プラグイン用API
[AX] Export filter. アーカイブ展開プラグイン用API
未実装可: 常に -1 を返しても良い
オプション: オプションAPI。常に -1 を返しても良いし、APIがなくても良い
無API注意: 常に -1 を返したり、APIがないプラグインがある

コールバック

SUSIE_PROGRESS

Plug-in に関する情報を取得します。Plug-in の種類、表示用の名前、対応拡張子が得られます。
extern "C" int __stdcall GetPluginInfo(int infono, LPSTR buf, int buflen);
extern "C" int __stdcall GetPluginInfoW(int infono, LPWSTR buf, int buflen);

パラメータ
[in] int infono
 0  Plug-in APIバージョン
    "00IN" ([IF] 画像展開プラグイン)または "00AM" ([AX] アーカイブ展開プラグイン)が返ります。本家仕様としては他の指定が挙げられていますが、実際には使用されていないので、この２つに限定しています。
    ※ AtoB Converter(https://www.asahi-net.or.jp/~kh4s-smz/spi/abc/index.html)の出力Plug-inでは "T0XN" が定義されています。
 1  Plug-in の名前、バージョン、Copyright

 2n+2  対応拡張子 ("*.JPG" "*.RGB;*.Q0" など。ワイルドカードを「;」で区切る)
 2n+1  ファイル形式名 (ファイルダイアログ等のファイルタイプ名として使われます)

[out] LPSTR buf
 結果文字列の受け取り先。buflen が不足しているときは末尾 \0 が無い場合があります。

[in] int buflen
 buf の長さ（ \0 の分を含む）。
 Susie では infono = 0 では 8、infono = 1 では 128、 2以降は 255 が指定されているので、アプリケーションは前記以上の大きさを推奨します。

戻り値
 文字列の長さ(\0 を含まない)。infono が無効の場合は 0 になります。
 全ての対応拡張子を調べるために戻り値が 0 になるまで infono の値を増やして呼び出される使い方がされます。
 尚、\0 を含んだ長さにしている Plug-in が多いので注意が必要です。

実装
 [IF][AX] GetPluginInfo:必須, GetPluginInfoW:オプション

IsSupported, IsSupportedW

ファイルに対応しているかを調べます。
extern "C" int __stdcall IsSupported(LPCSTR filename, const void *dw);
extern "C" int __stdcall IsSupportedW(LPCWSTR filename, const void *dw);

パラメータ
[in] int filename
  ファイル名。フルパス推奨です。
[in] LPCSTR / LPCWSTRdw
  ファイル先頭部(2Kbyte)を読み込んだバッファへのポインタ
  ファイルサイズが 2Kbyte 以下の場合もバッファは 2Kbyte 確保し、余分は 0 で埋めること。
  (使用禁止) dw の値が 16bit の範囲に収まるときは、ファイルハンドルと見なします。また、ファイルポインタはアプリケーション側で予め指定します。
  ファイルハンドル指定は、現在の 32bit Windows ではファイルハンドルが 16bit を超える場合があるので使用禁止です。

戻り値
  0 非対応
  0以外 対応している画像フォーマットである

解説
 各 Plug-in は基本的に渡されたファイルのヘッダを調べ、自分の対応したファイルフォーマットであるかどうかを調べます。
 Susie の純正 Plug-inではfilenameを使用していません。
 Susie は、画像・書庫に対して必ず１回は使用しています。
 IsSupported で 対応と判断されても後続の API(GetPicture等) で対応ファイルでないとエラーが出ることがあります。アプリケーションは、前記状況のときに別の Plug-in を使うにすると失敗が減ります。
 ※ Plug-in によっては、ここで得られたファイル名をファイルイメージ渡しの GetPicture, GetArchiveInfo 等で利用することがあります。
 ※ lhasad.spi では 2Kbyte 以上参照する記載があります（spi_api.txt の「バッファサイズ2Kbyte以上は自己解凍型LHa対応のため」）。
 ※ ファイルハンドル渡しはファイルハンドルが 16bit に納まらないことがあるため使用禁止です。

実装
 [IF][AX] IsSupported:必須, IsSupportedW:オプション

ConfigurationDlg

Plug-in 定義の aboutダイアログか設定ダイアログを実行します。
extern "C" int __stdcall ConfigurationDlg(HWND hWnd, int function);

パラメータ
[in] HWND hWnd
  親ウィンドウのウィンドウハンドル
[in] int function

動作
  0  Plug-inのaboutダイアログ表示(必要であれば)
  1  設定ダイアログ表示

戻り値
  エラーコード

実装
 [IF][AX] ConfigurationDlg:オプション(Susie 0.40以降)

GetPictureInfo, GetPictureInfoW

画像ファイルの情報を取得します。
extern "C" int __stdcall GetPictureInfo(LPCSTR buf, LONG_PTR len, unsigned int flag, struct PictureInfo *lpInfo);
extern "C" int __stdcall GetPictureInfoW(LPCWSTR buf, LONG_PTR len, unsigned int flag, struct PictureInfo *lpInfo);

パラメータ
[in]  LPCSTR / LPCWSTR buf
  入力がファイルの場合: ファイル名
  メモリーの場合: ファイルイメージへのポインタ
[in]  LONG_PTR len
  入力がファイルの場合: 読込み開始オフセット(MacBin対応のため)
  メモリーの場合: メモリサイズ
[in]  int flag
  追加情報 0000 0000 0000 0SSS
    SSS : 入力形式
      000 : ディスクファイル
      001 : メモリ上のイメージ
[out] struct PictureInfo *lpInfo

戻り値
  エラーコード

解説
  実際の画像の情報ではなく、プロパティ表示用のヘッダ等から入手した情報が使われたりするため、GetPictureで得られる画像と合わない事も生じます。このため、GetPictureInfo は参考情報として扱い、GetPicture を使った後は、GetPicture の画像の情報を利用する必要があります。

 プラグインによっては、lpInfo の各要素を全て更新しないことがあります。
  本家も left, top を更新していないプラグインがいくつかあります。
  このため、アプリケーションは、GetPictureInfo を使う前に lpInfo の各要素を初期化しておくことをおすすめします。

実装
 [IF] GetPictureInfo:無API注意, GetPictureInfoW:オプション

構造体
#pragma pack(push, 1)
struct PictureInfo
{
   long left, top;    // 画像を展開する位置
   long width;       // 画像の幅(pixel)
   long height;      // 画像の高さ(pixel)
   WORD x_density;   // 画素の水平方向密度
   WORD y_density;   // 画素の垂直方向密度
   short colorDepth; // １画素当たりのbit数
   #ifdef _WIN64
       char dummy[2]; // アラインメント合わせ用(64bit版)
   #endif
   HLOCAL hInfo;     // 画像内のテキスト情報(Windowsのコードページ、UTF-8の場合はBOMを付けること)。未使用: NULL
};
#pragma pack(pop)
※ 32bit版の構造体のアラインメント合わせは 1 のため、hInfo のアラインメントは通常と異なります。
※ 64bit版の hInfo のアラインメントが合わないため、アプリケーション側で hInfo を正しく取得できない場合があります。例えば、GetPictureInfo の呼び出し前に hInfo = 0x7f7f7f7f7f7f7f7f としておき、呼び出し後に (hInfo & 0xff00000000000000) == 0x7f00000000000000 を満たしている場合、アラインメントずれを検出できます。

GetPicture, GetPictureW, GetPreview, GetPreviewW

画像ファイルからビットマップを取得します。
extern "C" int __stdcall GetPicture(LPCSTR buf, LONG_PTR len, unsigned int flag, HLOCAL *pHBInfo, HLOCAL *pHBm, SUSIE_PROGRESS lpPrgressCallback, LONG_PTR lData);
extern "C" int __stdcall GetPictureW(LPCWSTR buf, LONG_PTR len, unsigned int flag, HLOCAL *pHBInfo, HLOCAL *pHBm, SUSIE_PROGRESS lpPrgressCallback, LONG_PTR lData);

extern "C" int __stdcall GetPreview(LPCSTR buf, LONG_PTR len, unsigned int flag, HLOCAL *pHBInfo, HLOCAL *pHBm, SUSIE_PROGRESS lpPrgressCallback, LONG_PTR lData);
extern "C" int __stdcall GetPreviewW(LPCWSTR buf, LONG_PTR len, unsigned int flag, HLOCAL *pHBInfo, HLOCAL *pHBm, SUSIE_PROGRESS lpPrgressCallback, LONG_PTR lData);

パラメータ
[in]  LPCSTR / LPCWSTR buf
  入力がファイルの場合: ファイル名
  メモリーの場合: ファイルイメージへのポインタ
[in]  LONG_PTR len
  入力がファイルの場合: 読込み開始オフセット(MacBin対応のため)
  メモリーの場合: メモリサイズ
[in]  int flag
  追加情報 0000 0000 0000 0SSS
    SSS : 入力形式
      000 : ディスクファイル
      001 : メモリ上のイメージ
[out] HLOCAL *pHBInfo
  BITMAPINFO 構造体が納められたメモリハンドルが返される
[out] HLOCAL *pHBm
  ビットマップデータ本体のメモリハンドルが返される
[in][option] SUSIE_PROGRESS lpPrgressCallback
  途中経過を表示するコールバック関数へのポインタ
  NULL の場合、plug-in は処理が終了するまでプロセスを占有し、中断も出来ません。
  ただし、NULL を許容しないプラグインがあるので、アプリケーションはダミーでも関数を指定することを推奨します。
[in][option] LONG_PTR lData
  コールバック関数に渡す変数。

戻り値
  エラーコード

解説
  プラグインはLocalAllocによって必要なメモリーを確保し、そのハンドルを返します。
  アプリケーションはLocalLockでポインタを取得し、LocalUnlock, LocalFreeによってメモリーを解放する必要があります。
  Susie は 16/32bit, RLE bitmap に完全に対応していません。また、トップダウンDIBに対応していません。

  GetPreview / GetPreviewW は、プレビュー用のデータやアルゴリズムがあればそれを使用してビットマップを用意します。このため GetPicture / GetPictureW と画像サイズが異なります。また、アプリケーションは、GetPreview が -1 を返してきたときに GetPicture を使用するようにします。

実装
 [IF] GetPicture:必須, GetPictureW:オプション, GetPreview:未実装可,無API注意,  GetPreviewW:オプション

GetArchiveInfo, GetArchiveInfoW

アーカイブ内のすべてのファイルの情報を取得します。
extern "C" int __stdcall GetArchiveInfo(LPCSTR buf, LONG_PTR len, unsigned int flag, HLOCAL *lphInf);
extern "C" int __stdcall GetArchiveInfoW(LPCWSTR buf, LONG_PTR len, unsigned int flag, HLOCAL *lphInf);

パラメータ
[in]  LPCSTR / LPCWSTR buf
  入力がファイルの場合: ファイル名
  メモリーの場合: ファイルイメージへのポインタ
[in]  LONG_PTR len
  入力がファイルの場合: 読込み開始オフセット(MacBin対応のため)
  メモリーの場合: メモリサイズ
[in]  int flag
  追加情報 0000 0000 0000 0SSS
    SSS : 入力形式
      000 : ディスクファイル
      001 : メモリ上のイメージ
[out] HLOCAL *lphInf
  fileInfW (ANSI版), fileInfoW (UNICODE版) の配列の LOCAL メモリハンドルを受け取る変数へのポインタ。
   エラーの時は、NULL を設定します。戻り値が 0 以外の時も必ず設定が必要です。
  アプリケーションはLocalLockでポインタを取得し、LocalUnlock, LocalFreeによってメモリーを解放する必要があります。
   method[0] == '\0' のときは終端です。このときの fileInfoW の大きさは method[0] の大きさのみであって、他の要素を参照しようとするとアクセス違反になる場合があります。

戻り値
  エラーコード
  lhasad.spi では常に 2 を返します。このため、lphInf が NULL か NULL でないかの判断も必要です。

解説
 ファイル名のディレクトリ部は fileInfo/W.path、ファイル名部は fileInfo/W.filenam に格納されます。

ファイル filename.ext の場合、
path = ""、filename = "filename.ext"
ファイル dir1\dir2\filename.ext の場合、
path = "dir1\\dir2\\"、filename = "filename.ext"
ディレクトリ dir1\dir2\ の場合は、
path = "dir1\\dir2\\"、filename = ""

 尚、一部の Plug-in は、ディレクトリ部を含めて filename に格納しています。またパスの区切りに「/」を用いている場合があります。

実装
 [AX] GetArchiveInfo:必須, GetArchiveInfoW:オプション

構造体
#define SUSIE_PATH_MAX 200
// Susie 用の time_t(UNIX時間)。spi では 32bit、sph では 64bit。
// FILETIME に変換するときは、(timestamp * 10000000) + 0x19db1ded53e8000
typedef ULONG_PTR susie_time_t;

#pragma pack(push, 1)
struct {
  unsigned char  method[8];  // 圧縮法の種類
  ULONG_PTR      position;   // ファイル上での位置 ※位置と関係ないインデックスとして使うこともある
  ULONG_PTR      compsize;   // 圧縮されたサイズ
  ULONG_PTR      filesize;   // 元のファイルサイズ ※ 展開しないとサイズが分からない場合は設定されないことがある
  susie_time_t   timestamp;  // ファイルの更新日時
  char           path[SUSIE_PATH_MAX];  // ディレクトリ。末尾は \\ を推奨。
  char           filename[SUSIE_PATH_MAX];  // ファイル名。\\ や / は使用不可
  unsigned long  crc;        // CRC
  #ifdef _WIN64
    char dummy[4]; // アラインメント合わせ用(64bit版)
  #endif
} fileInfo;
#pragma pack(pop)

#pragma pack(push, 1)
struct {
  unsigned char  method[8];  // 圧縮法の種類
  ULONG_PTR      position;   // ファイル上での位置 ※位置と関係ないインデックスとして使うこともある
  ULONG_PTR      compsize;   // 圧縮されたサイズ
  ULONG_PTR      filesize;   // 元のファイルサイズ ※ 展開しないとサイズが分からない場合は設定されないことがある
  susie_time_t   timestamp;  // ファイルの更新日時
  WCHAR          path[SUSIE_PATH_MAX];  // ディレクトリ。末尾は \\ を推奨。
  WCHAR          filename[SUSIE_PATH_MAX];  // ファイル名。\\ や / は使用不可
  unsigned long  crc;        // CRC
  #ifdef _WIN64
    char dummy[4]; // アラインメント合わせ用(64bit版)
  #endif
} fileInfoW;
#pragma pack(pop)

GetFile, GetFileW

アーカイブ内の指定ファイルを取得します。
extern "C" int __stdcall GetFile(LPCSTR src, LONG_PTR len, LPSTR dest, unsigned int flag, SUSIE_PROGRESS prgressCallback, LONG_PTR lData); extern "C" int __stdcall GetFileW(LPCWSTR src, LONG_PTR len, LPWSTR dest, unsigned int flag, SUSIE_PROGRESS prgressCallback, LONG_PTR lData);

パラメータ

[in] LPCSTR / LPCWSTR src
  入力がファイルの場合: ファイル名
  メモリーの場合: ファイルイメージへのポインタ(読込み開始オフセット含む)
[in] LONG_PTR len
  入力がファイルの場合: 読込み開始オフセット、GetArchiveInfo で得られる positionをそのまま使う。※位置と関係ないインデックスとして使うこともあるので、ファイル位置として想定しない方が良い。
  メモリーの場合: データサイズ
[in] or [out] LPSTR / LPWSTR dest
  出力先がファイルの場合: [in] 出力先ディレクトリ。fileInfo の path は使用されず、dest\filename の形で保存されます。
  メモリーの場合: [out] ファイルの入った LOCAL メモリーハンドルを受け取る変数へのポインタ。
[in] int flag
  追加情報 0000 0DDD 0000 0SSS
    SSS : 入力形式
      000 : ディスクファイル
      001 : メモリ上のイメージ
    DDD : 出力形式
      000 : ディスクファイル
      001 : メモリ上のイメージ
[in][option] SUSIE_PROGRESS lpPrgressCallback
  途中経過を表示するコールバック関数へのポインタ。
  NULL の場合、plug-in は処理が終了するまでプロセスを占有し、中断も出来ません。
  ただし、NULL を許容しないプラグインがあるのでダミーのコールバックを推奨します。
[in][option] LONG_PTR lData
  コールバック関数に渡す変数。

戻り値
  エラーコード

解説
  src と len の組み合わせで書庫ファイル中のファイルを指定して取得を行います。
  GetFile/W は予め GetArchiveInfo/W か GetFileInfo/W を実行し、struct fileinfo/W の情報を得る必要があります。
  src がファイル名の場合は、struct fileinfo/W 中の position を len として扱います。
  src がメモリイメージの場合は、ファイルのメモリイメージの先頭から前記 position の分だけずらしたメモリを指定します。
  len は struct fileinfo/W 中の compsize 以上が必要になります。

  プラグインはLocalAllocによって必要なメモリーを確保し、そのハンドルを返します。
  アプリケーションはLocalLockでポインタを取得し、LocalUnlock, LocalFreeによってメモリーを解放する必要があります。

実装
 [AX] GetFile:必須, GetFileW:オプション

GetFileInfo, GetFileInfoW

アーカイブ内の指定したファイルの情報を取得します。
extern "C" int __stdcall GetFileInfo(LPCSTR buf, LONG_PTR len, LPCSTR filename, unsigned int flag, struct fileInfo *lpInfo);
extern "C" int __stdcall GetFileInfoW(LPCWSTR buf, LONG_PTR len, LPCWSTR filename, unsigned int flag, struct fileInfoW *lpInfo);

パラメータ
[in] LPCSTR / LPCWSTR buf
  入力がファイルの場合: ファイル名
  メモリーの場合: ファイルイメージへのポインタ(読込み開始オフセット含む)
[in] LONG_PTR len
  入力がファイルの場合: 読込み開始オフセット、GetArchiveInfo で得られる positionをそのまま使う。※位置と関係ないインデックスとして使うこともあるので、ファイル位置として想定しない方が良い。
  メモリーの場合: データサイズ
[in] LPCSTR / LPCWSTR filename
  情報を取得するファイルのファイル名。アーカイブ内のディレクトリを含めて指定
[in] int flag
  追加情報 0000 0000 I000 0SSS
    SSS : 入力形式
      000 : ディスクファイル
      001 : メモリ上のイメージ
    I : ファイル名の case
     0 : ファイル名の大文字小文字を区別する
     1 : ファイル名の大文字小文字を同一視する。
[out] fileInfo/fileInfoW lpInfo
  情報を受け取る fileInfo 構造体へのポインタ

戻り値
  エラーコード

解説
  書庫ファイル中のファイル filename を指定して情報取得を行います。

  src がファイル名の場合は、struct fileinfo/W 中の position を len として扱います。
  src がメモリイメージの場合は、ファイルのメモリイメージの先頭から前記 position の分だけずらしたメモリを指定します。
  len は struct fileinfo/W 中の compsize 以上が必要になります。

  lpInfo の内容は、GetArchiveInfo/W から得られる struct fileinfo/W と同じ内容なので、GetArchiveInfo/W を先に使っていたときは、GetFileInfo/W を使わなくても GetFile/W を使用できます。

  Susie は、この API を現在使用していません。

実装
 [AX] GetFileInfo:無API注意, GetFileInfoW:オプション

CreatePicture (オプション、独自)

ビットマップを指定した拡張子に対応するファイル形式でエンコードします。
extern "C" int __stdcall CreatePicture(LPCSTR filepath, unsigned int flag, HLOCAL *pHBInfo, HLOCAL *pHBm, struct PictureInfo *lpInfo, SUSIE_PROGRESS progressCallback, LONG_PTR lData);
extern "C" int __stdcall CreatePictureW(LPCWSTR filepath, unsigned int flag, HLOCAL *pHBInfo, HLOCAL *pHBm, struct PictureInfo *lpInfo, SUSIE_PROGRESS progressCallback, LONG_PTR lData);

パラメータ
拡張子に対応したファイル形式でビットマップからファイルを作成します。

[in] LPCSTR / LPCWSTR buf
  保存するファイル名。拡張子がエンコードするファイルの種類を示す。対応していない拡張子の時は、デフォルトの種類でエンコードするか、2 を返す。
[in] flag
  追加情報 000E RDDD 0000 0000
    DDD : 出力形式
      000 : ディスクファイル
      001 : メモリ上のイメージ(未対応)
    R : 不明の拡張子の扱い
      0 : 規定のファイル形式で保存する(またはエラー 2を返す)
      1 : 常にエラー 2 を返す
    E : 追加情報(未実装)
      0 : 追加情報なし
      1 : 追加情報あり
[in] HLOCAL *pHBInfo
  BITMAPINFO 構造体が納められたメモリハンドル
[in] HLOCAL *pHBm
  ビットマップデータ本体のメモリハンドル
[in][option] struct PictureInfo *lpInfo
  pHBInfo にない情報を含めるときに使用します。lpInfo = NULL としても構いません。x_density, y_density, colorDepth は pHBInfo を参照するため、使用されません。
  ※将来保存形式を拡張する場合は、flag の B12 を 1 にして、この構造体の後ろに空白区切りのコマンドパラメータの文字列を追加する形を想定しています。
[in][option] SUSIE_PROGRESS lpPrgressCallback
  途中経過を表示するコールバック関数へのポインタ。
  NULL の場合、plug-in は処理が終了するまでプロセスを占有し、中断も出来ません。
  ただし、NULL を許容しないプラグインがあるのでダミーのコールバックを推奨します。
[in][option] LONG_PTR lData
  コールバック関数に渡す変数。

戻り値
  エラーコード

解説
AtoB Converter(https://www.asahi-net.or.jp/~kh4s-smz/spi/abc/index.html)の 出力Plug-in を参考にしています。

対応拡張子は、GetPluginInfo/W で得られる拡張子であり、「*.1st;*.2nd...」と複数記載されている場合は先頭の拡張子(.1st)のみ対応です。また、GetPluginInfo/W に列挙されていても対応していない場合があり，その時は規定の拡張子扱いになるか、エラー 2 になります。

実装
[IN] CreatePicture:独自API, オプション

コールバック

typedef int (__stdcall *SUSIE_PROGRESS)(int nNum, int nDenom, LONG_PTR lData);

  まず nNum == 0 でコールされ、nNum == nDenom になるまで
  定期的に呼ばれます。
  戻り値が 非0 の時、Plug-inは処理を中断します。

エラーコード

    0 : 正常終了
   -1 : その機能は実装されていない
    1 : コールバック関数が非0を返したので展開を中止した
    2 : 未知のフォーマット
    3 : データが壊れている
    4 : メモリーが確保出来ない
    5 : メモリーエラー（Lock出来ない、等）
    6 : ファイルリードエラー
    7 : （予約）
    8 : 内部エラー
    9 : ファイルライトエラー

bitmap仕様

やりとりするビットマップは、pHBInfo と pHBm に分かれて扱われます。それぞれの大きさは LocalSize で参照します。

pHBInfo
次のビットマップの情報が入ります。先頭 * はアプリケーション側で必須(Susie が対応している形式)となる対応形式です。
Plug-inとしては * 以外の形式も使用できますが、設定で * のみの形式に制限できることを推奨します。

  * BITMAPINFOHEADER (24bit のとき)
  * BITMAPINFOHEADER + パレット (1/4/8bit のとき)
    BITMAPINFOHEADER + BITFIELDS (16/24/32bit のとき)
    BITMAPV5HEADER (24bit のとき)
    BITMAPV5HEADER + パレット (1/4/8bit のとき)
    BITMAPV5HEADER + パレット + カラープロファイル(1/4/8bit のとき)
    BITMAPV5HEADER + カラープロファイル(16/24/32bit のとき)

pHBm
ビットマップそのものが入ります。

Plug-in を使うアプリケーションとして完全対応したい場合は、前記の全種類の対応に加え、次の仕様に対応する必要があります。Plug-in 側はこれらの形式を使わない設定を用意することを推奨します。
・トップダウンDIB(biHeight が負の値)
・16/32bit カラー
・1以外のアスペクト比(biXPelsPerMeter != biYPelsPerMeter)
・32bit BGRA (透過画像)
・カラープロファイル
・4/8bit RLE
・BGR, BGRA 以外の BITFIELDS 指定(RGBA, ABGRなど)
・8bit 以外の色深度(10bitグレーや 10bit * 3カラーなど)

また、「BMP Suite」(https://entropymine.com/jason/bmpsuite/)に上記仕様の BMP ファイルの例や、破損 BMP ファイルの例が用意されていますので、これら例を読み込んでも異常動作を起こさないように対応することをお勧めします。

参考：ファイルに保存するときの配置
BITMAPFILEHEADER, BITMAPINFOHEADER, [パレット又はBITFIELDS], ビットマップ
BITMAPFILEHEADER, BITMAPV5HEADER, [パレット又はBITFIELDS], ビットマップ, [カラープロファイル]

参考：クリップボードに保存するときの配置
BITMAPINFOHEADER, [パレット又はBITFIELDS], ビットマップ
BITMAPV5HEADER, [パレット又はBITFIELDS], ビットマップ, [カラープロファイル]
※ BITMAPV5HEADERを使う場合は CF_DIBV5(BITMAPV5HEADER) と CF_DIB(BITMAPINFOHEADER) をこの順に登録する必要がある。

その他

Susie 0.47b は、トップダウンDIB に対応していません。
また、カタログ表示は更に多くの 16bit DIB, 32bit DIB が扱えない制限があります。
アプリケーションは、IsSupported を必ず使用してください。その後の API でメモリ渡しを使うと、Plug-in がファイル名を受け取る唯一のチャンスとなるなど、他のAPIで不足している情報を集めることがあるためです。
API は主に次の使い方がされます。UNICODE 版APIを使うときも同じ順です。
画像展開
IsSupported - GetPicture
IsSupported - GetPictureInfo - GetPicture

アーカイブ展開
IsSupported - GetArchiveInfo - [GetFile]n
IsSupported - GetArchiveInfo - [GetFileInfo - GetFile]n
IsSupported - GetArchiveInfo - [IsSupported - GetFileInfo - GetFile]n
ファイルサイズが 0、または画像ファイルのヘッダサイズに満たない大きさのファイルを、ファイル名かメモリイメージで渡されることがあります。Plug-in 側はこれらのファイルでも異常終了しないように対策する必要があります。
マルチスレッドによる API の複数スレッドの同時使用は保証されません。ただし、マルチスレッドで使用するアプリケーションがあるため、可能なら対応することをお勧めします。対応していない場合はそのことを言及することをお勧めします。
複数のスレッドで API を使う場合、一連の操作(IsSupported～GetPicture/GetFile まで)を同じスレッドで行う必要があります。
IsSupportedやGetArchiveInfoで得られた情報をスレッド単位でキャッシュしている場合があります。

MacBin(Mac Binary)対応について
Classic Mac OS(Mac OS X 以前の Mac OS) 上で作成した画像ファイルの一部には、画像本体(データフォーク)の先頭に追加される 128bytes のマックバイナリヘッダと、画像本体の後ろに追加されるリソースフォークがあり、そのまま読み込んでも画像として扱えないことがあります。
Susie Plug-in で MacBin 付き画像を扱う場合は、アプリケーション側で Susie Plug-in にファイルポインタを 128 バイト分ずらすことを指示したり、ファイル先頭から 128 バイト分ずらしたメモリを渡したりすることで対応する必要があります。

テスト用プログラム

動作確認用として次のテスト用プログラムを用意しました。
Runspi / Runsph / Runspia
Plug-in と対応するファイルを読み込んで、Plug-in の API を一通り試すことができるコンソールアプリケーションです。
Extend convert Susie Plug-in for developer
アプリケーションに読み込ませて、サンプル画像・サンプル書庫を扱えるかどうかを確認したり、API の使用状況をロギングしたりすることができる Susie Plug-in です。

参考資料

Susie Plug-in 関係

Susieの部屋「Susie 32bit Plug-in 仕様 rev5」(http://www.digitalpad.co.jp/~takechin/download.html)
kana's Home Page 「Susie Plug-in Specification Rev4+α on Win32」(https://www2f.biglobe.ne.jp/~kana/spi_api/index.html)
SHIMITEI 「Susie Plug-inプログラミング」(https://www.asahi-net.or.jp/~kh4s-smz/spi/index.html)
プログラミング - とぅいんくる☆は～つ「Susie Plug-in Programming Guide」(http://home.netyou.jp/cc/susumu/progSusie.html)

Windows Bitmap 関係

Jason Summers’s web site 「BMP Suite」(https://entropymine.com/jason/bmpsuite/)

Homeへ戻る

TORO's Library

Susie 32bit / 64bit Plug-in の仕様(2024-9-28版)

構造体一覧

コールバック

GetPicture, GetPictureW, GetPreview, GetPreviewW

コールバック

Software

Hardware

Data

Message Board