home *** CD-ROM | disk | FTP | other *** search
/ DOS/V Power Report 1996 November / VPR9611A.ISO / ols / win95 / spi32005 / spi32005.lzh / SPI_API.TXT < prev   
Text File  |  1996-06-06  |  15KB  |  365 lines
  1. Susie 32bit Plug-in 仕様 rev4
  2.  
  3. １．はじめに
  4.   Susie 32bit Plug-in は Windows の DLL であり、後述の API により Susie 以外の
  5.   ソフトウェアからも簡単に使う事が出来ます。
  6.   また、この仕様通りにPlug-inを作れば Susie を新しい画像フォーマットに
  7.   対応させる事が可能です。
  8.  
  9. ２．Plug-in APIのバージョン
  10.   今後の拡張性を持たせるため、Plug-inにAPIのバージョン番号がつきます。
  11.   このバージョン番号はすべてのバージョンに共通である関数'GETPLUGININFO'によって
  12.   取得出来ます。
  13.   バージョン番号は基本的に4byteのコードで以下の意味を持ちます。
  14.  
  15.       00 I N
  16.       ~T T T
  17.        | | +-- N : Normal,  M : Multi-picture
  18.        | +---- I : Import filter, X : Export filter, A : Archive extractor
  19.        +------ Virsion No.
  20.  
  21.   今回同梱されているPlug-inはすべて '00IN'Typeです。
  22.  
  23. ３．共通関数
  24.   ・GetPluginInfo - Plug-inに関する情報を得る
  25.  
  26.     Prototype:
  27.       extern "C" int _export PASCAL GetPluginInfo(int infono,
  28.                                                 LPSTR buf,int buflen);
  29.     Parameter:
  30.       int infono : 取得する情報番号
  31.                       0   : Plug-in APIバージョン
  32.                       1   : Plug-in名、バージョン及び copyright
  33.                             (SusieのAbout..に表示されます)
  34.                       2n+2: 代表的な拡張子 ("*.JPG" "*.RGB;*.Q0" など)
  35.                       2n+3: ファイル形式名
  36.                             (SusieのOPENダイアログに表示されます)
  37.       LPSTR buf    : 情報を納めるバッファ
  38.       int buflen : バッファ長(byte)
  39.  
  40.     Return:
  41.       バッファに書き込んだ文字数を返します。
  42.       情報番号が無効の場合、0を返します。
  43.  
  44.     解説:
  45.       情報番号0と1はすべてのバージョンで共通とします。
  46.       2以降は二つづつ組みでSusieのOPENダイアログで用いる情報です。
  47.       一つのplug-inで複数の画像フォーマットに対応している場合は
  48.       その数だけ拡張子とファイル形式名を用意します。
  49.  
  50. ４．'00IN'の関数
  51.   ・IsSupported - 展開可能な(対応している)ファイル形式か調べる。
  52.     Prototype:
  53.       extern "C" int _export PASCAL IsSupported(LPSTR filename,DWORD dw);
  54.  
  55.     Parameter:
  56.       LPSTR filename : ファイルネーム
  57.       DWORD dw       : 上位ワードが  0  のとき:
  58.                            ファイルハンドル
  59.                        上位ワードが 非0 のとき:
  60.                            ファイル先頭部(2Kbyte以上)を読み込んだバッファへの
  61.                            ポインタ
  62.                            ファイルサイズが2Kbyte以下の場合もバッファは2Kbyte
  63.                            確保し、余分は 0 で埋めること
  64.  
  65.     Return:
  66.       対応している画像フォーマットであれば非0を返す
  67.  
  68.     解説:
  69.       各Plug-inは基本的に渡されたファイルのヘッダを調べ、自分の対応したファイル
  70.       フォーマットであるかどうかを調べる。
  71.       まれにファイル名(拡張子)を判断材料として必要としたり、複数のファイルで
  72.       構成されている場合があるので、ファイル名(フルパス)も引数に加えた。
  73.       今回配布のPlug-inではfilenameは使われていない。
  74.  
  75.  
  76.   ・GetPictureInfo - 画像ファイルに関する情報を得る
  77.     Prototype:
  78.       extern "C" int _export PASCAL GetPictureInfo(
  79.          LPSTR buf,long len,unsigned int flag,struct PictureInfo *lpInfo);
  80.  
  81.     Parameter:
  82.       LPSTR buf : 入力がファイルの場合 ファイル名
  83.                         メモリーの場合 ファイルイメージへのポインタ
  84.       long len  : 入力がファイルの場合 読込み開始オフセット(MacBin対応のため)
  85.                         メモリーの場合 データサイズ
  86.       unsigned int flag : 追加情報 xxxx xxxx xxxx xSSS
  87.                   SSS : 入力形式
  88.                         0 : ディスクファイル
  89.                         1 : メモリ上のイメージ
  90.       struct PictureInfo *lpInfo :
  91.                   struct PictureInfo
  92.                   {
  93.                     long left,top;    画像を展開する位置
  94.                     long width;       画像の幅(pixel)
  95.                     long height;      画像の高さ(pixel)
  96.                     WORD x_density;   画素の水平方向密度
  97.                     WORD y_density;   画素の垂直方向密度
  98.                     short colorDepth; １画素当たりのbit数
  99.                     HLOCAL hInfo;    画像内のテキスト情報
  100.                   };
  101.                   hInfoには必要に応じてPlug-inが確保したGlobalメモリーの
  102.                   ハンドルが格納される。
  103.  
  104.     Return:
  105.       エラーコード。0なら正常終了。
  106.  
  107.   ・GetPicture - 画像を展開する
  108.     Prototype:
  109.       extern "C" int _export PASCAL GetPicture(
  110.               LPSTR buf,long len,unsigned int flag,
  111.               HANDLE *pHBInfo,HANDLE *pHBm,
  112.               FARPROC lpPrgressCallback,long lData);
  113.  
  114.     Parameter:
  115.       LPSTR buf : 入力がファイルの場合 ファイル名
  116.                         メモリーの場合 ファイルイメージへのポインタ
  117.       long len  : 入力がファイルの場合 読込み開始オフセット(MacBin対応のため)
  118.                         メモリーの場合 データサイズ
  119.       unsigned int flag : 追加情報 xxxx xxxx xxxx xSSS
  120.                   SSS : 入力形式
  121.                         0 : ディスクファイル
  122.                         1 : メモリ上のイメージ
  123.       HLOCAL *pHBm    : ビットマップデータ本体のメモリハンドルが返される
  124.       HLOCAL *pHBInfo : BITMAPINFO 構造体が納められたメモリハンドルが
  125.                              返される。
  126.       FARPROC lpPrgressCallback :
  127.                 途中経過を表示するコールバック関数へのポインタ。
  128.                 MakeProcInstance を用いて求める。
  129.                 NULLの場合、plug-inは処理が終了するまでプロセスを占有し、
  130.                 中断も出来ません。
  131.                 コールバック関数のprototype:
  132.                   int PASCAL ProgressCallback(
  133.                                         int nNum,int nDenom,long lData);
  134.                   まず nNum==0 でコールされ、nNum==nDenom になるまで
  135.                   定期的に呼ばれる。
  136.                   戻値が 非0 の時、Plug-inは処理を中断する。
  137.       long lData : コールバック関数に渡すlongデータ。
  138.                   ポインタ等を必要に応じて受け渡せる。
  139.  
  140.     Return:
  141.       エラーコード。0なら正常終了。
  142.  
  143.     解説:
  144.       プラグインはLocalAllocによって必要なメモリーを確保し、そのハンドルを
  145.       返す。
  146.       アプリケーションはLocalFreeによってメモリーを開放する必要がある。
  147.  
  148.   ・GetPreview - プレビュー・カタログ表示用画像縮小展開ルーティン
  149.     Prototype:
  150.       extern "C" int _export PASCAL GetPreview(
  151.               LPSTR buf,long len,unsigned int flag,
  152.               HANDLE *pHBInfo,HANDLE *pHBm,
  153.               FARPROC lpPrgressCallback,long lData);
  154.  
  155.     Parameter:
  156.       GETPICTURE参照。
  157.  
  158.     Return:
  159.       エラーコード。0なら正常終了。
  160.       この関数はオプションであり、未対応の場合は -1 を返す。
  161.  
  162.     解説:
  163.       プレビュー等で用いる縮小された画像をファイルから作成する。
  164.       JPEGの様に、アルゴリズムの関係で縮小されたサイズでは高速に展開出来る
  165.       ときにこの関数をインプリメントする。
  166.       今回配布のPlug-inでは IFJPEG.PLG のみ対応(1/4サイズで展開)している。
  167.       未対応の場合、Susieは通常の展開ルーティンを用いて展開した後
  168.       縮小処理を行う。
  169.       （対応していても縮小ロードされた画像を更にサイズ調整している）
  170.       プラグインはLocalAllocによって必要なメモリーを確保し、そのハンドルを
  171.       返す。
  172.       アプリケーションはLocalFreeによってメモリーを開放する必要がある。
  173.  
  174.   ・エラーコード
  175.     0 : 正常終了
  176.    -1 : その機能はインプリメントされていない
  177.     1 : コールバック関数が非0を返したので展開を中止した
  178.     2 : 未知のフォーマット
  179.     3 : データが壊れている
  180.     4 : メモリーが確保出来ない
  181.     5 : メモリーエラー（Lock出来ない、等）
  182.     6 : ファイルリードエラー
  183.     7 : （予約）
  184.     8 : 内部エラー
  185.  
  186. ５．'00AM'の関数 (暫定)
  187.  
  188.   ・IsSupported - 展開可能な(対応している)ファイル形式か調べる。
  189.     Prototype:
  190.       extern "C" int _export PASCAL IsSupported(LPSTR filename,DWORD dw);
  191.  
  192.     Parameter:
  193.       LPSTR filename : ファイルネーム
  194.       DWORD dw       : 上位ワードが  0  のとき:
  195.                            ファイルハンドル
  196.                        上位ワードが 非0 のとき:
  197.                            ファイル先頭部(2Kbyte以上)を読み込んだバッファへの
  198.                            ポインタ
  199.                            ファイルサイズが2Kbyte以下の場合もバッファは2Kbyte
  200.                            確保し、余分は 0 で埋めること
  201.  
  202.     Return:
  203.       対応している画像フォーマットであれば非0を返す
  204.  
  205.     解説:
  206.       詳しくは'00IN'のISSUPPORTED関数を参照の事。
  207.       引数dwで渡すバッファサイズ2Kbyte以上は自己解凍型LHa対応のため。
  208.  
  209.   ・GetArchiveInfo - アーカイブ内のすべてのファイルの情報を取得する
  210.     Prototype:
  211.       extern "C" errcode _export PASCAL GetArchiveInfo(LPSTR buf,long len,
  212.             unsigned int flag,HLOCAL *lphInf);
  213.  
  214.     Parameter:
  215.       LPSTR buf : 入力がファイルの場合 ファイル名
  216.                         メモリーの場合 ファイルイメージへのポインタ
  217.       long len  : 入力がファイルの場合 読込み開始オフセット(MacBin対応のため)
  218.                         メモリーの場合 データサイズ
  219.       unsigned int flag : 追加情報 xxxx xxxx xxxx xSSS
  220.                   SSS : 入力形式
  221.                         0 : ディスクファイル
  222.                         1 : メモリ上のイメージ
  223.       HLOCAL *lphInf
  224.                 : ファイル情報の入ったハンドルを受け取る変数へのポインタ。
  225.                   Plug-in内で確保されたLOCALメモリーに次の構造体配列が
  226.                   書き込まれ、そのハンドルが返される。
  227.                   method[0]=='\0'で終端。
  228.                         typedef struct
  229.                         {
  230.                             unsigned char method[8];    圧縮法の種類
  231.                             unsigned long position;     ファイル上での位置
  232.                             unsigned long compsize;     圧縮されたサイズ
  233.                             unsigned long filesize;     元のファイルサイズ
  234.                             time_t timestamp;           ファイルの更新日時
  235.                             char path[200];             相対パス
  236.                             char filename[200];         ファイルネーム
  237.                             unsigned long crc;         CRC
  238.                         } fileInfo;
  239.  
  240.     Return:
  241.       エラーコード。0なら正常終了。
  242.  
  243.   ・GetFileInfo - アーカイブ内の指定したファイルの情報を取得する
  244.     Prototype:
  245.       extern "C" errcode _export PASCAL GetFileInfo(LPSTR buf,long len,
  246.                     LPSTR filename, unsigned int flag,fileInfo *lpInfo);
  247.     Parameter:
  248.       LPSTR buf : 入力がファイルの場合 ファイル名
  249.                         メモリーの場合 ファイルイメージへのポインタ
  250.       long len  : 入力がファイルの場合 読込み開始オフセット(MacBin対応のため)
  251.                         メモリーの場合 データサイズ
  252.       LPSTR filename : 情報を取得するファイルのファイルネーム
  253.                         アーカイブ内の相対パスを含めて指定
  254.       unsigned int flag : 追加情報 xxxx xxxx Ixxx xSSS
  255.                   SSS : 入力形式
  256.                         0 : ディスクファイル
  257.                         1 : メモリ上のイメージ
  258.                   I : 0 : ファイル名の大文字小文字を区別する
  259.                       1 : ファイル名の大文字小文字を同一視する。
  260.       fileInfo *lpInfo
  261.                 : 情報を受け取るfileInfo構造体へのポインタ
  262.  
  263.     Return:
  264.       エラーコード。0なら正常終了。
  265.  
  266.   ・GetFile - アーカイブ内のファイルを取得する
  267.     Prototype:
  268.       extern "C" errcode _export PASCAL GetFile(LPSTR src,long len,
  269.                 LPSTR dest,unsigned int flag,
  270.                 FARPROC prgressCallback,long lData);
  271.  
  272.     Parameter:
  273.       LPSTR src  : 入力がファイルの場合 ファイル名
  274.                         メモリーの場合 ファイルイメージへのポインタ
  275.       long len   : 入力がファイルの場合 読込み開始オフセット
  276.                         メモリーの場合 データサイズ
  277.       void far *dest : 出力先がファイルの場合
  278.                               出力先ディレクトリ
  279.                                (書庫内の相対パスは無視される)
  280.                         メモリーの場合 
  281.                               ファイルの入ったLOCALメモリーハンドルを受け取る
  282.                               変数へのポインタ。
  283.       unsigned int flag  : 追加情報 xxxx xDDD xxxx xSSS
  284.                   SSS : 入力形式
  285.                         0 : ディスクファイル
  286.                         1 : メモリ上のイメージ
  287.                   DDD : 出力形式
  288.                         0 : ディスクファイル
  289.                         1 : メモリ上のイメージ
  290.       FARPROC lpPrgressCallback :
  291.                 途中経過を表示するコールバック関数へのポインタ。
  292.                 MakeProcInstance を用いて求める。
  293.                 NULLの場合、plug-inは処理が終了するまでプロセスを占有し、
  294.                 中断も出来ません。
  295.                 コールバック関数のprototype:
  296.                   int PASCAL ProgressCallback(
  297.                                         int nNum,int nDenom,long lData);
  298.                   まず nNum==0 でコールされ、nNum==nDenom になるまで
  299.                   定期的に呼ばれる。
  300.                   戻値が 非0 の時、Plug-inは処理を中断する。
  301.       long lData : コールバック関数に渡すlongデータ。
  302.                   ポインタ等を必要に応じて受け渡せる。
  303.  
  304.     Return:
  305.       エラーコード。0なら正常終了。
  306.  
  307.     解説:
  308.       プラグインはLocalAllocによって必要なメモリーを確保し、そのハンドルを
  309.       返す。
  310.       アプリケーションはLocalFreeによってメモリーを開放する必要がある。
  311.  
  312. ６．Plug-inの使い方
  313.   Plug-inはDLLですから、通常のDLLと同じ用に次の２つの方法でアプリケーションに
  314.   リンク出来ます。
  315.  
  316.   1) DLLからインポートライブラリを作ってリンクする
  317.     implib.exe や implibw.exe を使ってPlug-inからインポートライブラリを
  318.     作って、これをアプリケーションにリンクします。
  319.     この方法は簡単ですが、特定のPlug-inしか使えません。
  320.   2) LoadLibrary で必要に応じてリンクする。
  321.     この方法は少々手間がかかりますが、検索して見つかったPlug-inを動的に
  322.     用いることができます。
  323.  
  324.   通常は1)の方法が用いられますが、複数のフォーマットに対応する必要がある
  325.   場合には2)の方法をおすすめします。
  326.   2)の方法を用いるものとして全体の流れを説明します。
  327.  
  328.   1.Plug-inを検索する。
  329.     Plug-inのあるディレクトリを"*.plg"で検索し、見つかったものを
  330.     LoadLibrary でロードします。
  331.     GetProcAddress で GETPLUGININFO 関数へのポインタを取得し、
  332.     GETPLUGININFO 関数にて情報番号0のPlug-inバージョンを確かめます。
  333.     対応しているバージョンならPlug-inリストに加えます。
  334.     対応していないものならFreeLibraryで忘れずに開放します。
  335.  
  336.   2.画像ファイルに合ったPlug-inを探す。
  337.     画像ファイルをロードする必要が生じたならまずそのファイルを_lopen等で
  338.     オープンします。
  339.     次に Plug-inリストにしたがって順に ISSUPPORTED 関数を呼び、対応した
  340.     Plug-inを探します。MacBinary が付いている可能性があるので、offset=0で
  341.     だめな場合は offset=128 でもう一度探すと良いでしょう。
  342.  
  343.   3.画像を展開する。
  344.     対応したPlug-inが見つかったらそのPlug-inの GETPICTURE 関数でロードします。
  345.     この時、CALLBACK関数を用意出来るなら MakeProcInstance にてポインタを
  346.     取得し、GETPICTURE 関数に渡します。
  347.     CALLBACK関数内で PeekMessage を使う事で他のプロセスに(そして自分にも)
  348.     実行の機会を与えるとスマートです。
  349.  
  350.   4.Plug-inを開放する。
  351.     アプリケーションを終了する時には忘れずに LoadLibrary したPlug-inすべてを
  352.     FreeLibrary で開放しましょう。
  353.  
  354.  
  355. ７．Plug-inの仕様と使用に関して
  356.   Plug-inを作りたい、もしくは使いたいがこれではよくわからん、という方は
  357.   下記IDまでお問い合わせ下さい。なにかしら助言出来ると思います。（返事が
  358.   遅くなっても怒らないでね(^_^;)）
  359.   また、APIの仕様に関しての御意見もお待ちしております。APIバージョンアップ時
  360.   に参考にさせていただきます。このバージョンは Susie の内部クラスのI/Fの
  361.   ほとんどそのままなので汎用性に欠けますし(^_^;)
  362.   転載等に関しては plugin.txt を参照して下さい。
  363.  
  364.     Nifty-serve GGB01506   竹村嘉人 (たけちん)
  365.