home *** CD-ROM | disk | FTP | other *** search
/ DOS/V Power Report 1996 February / VPR9602A.ISO / fwindows / spi32002 / spi_api.txt < prev   
Text File  |  1995-05-01  |  15KB  |  353 lines
  1. Susie 32bit Plug-in 仕様 rev3
  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 FAR 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 FAR PASCAL IsSupported(LPSTR filename,DWORD dw);
  54.  
  55.     Parameter:
  56.       LPSTR filename : ファイルネーム
  57.       DWORD dw       : 上位ワードが  0  のとき:
  58.                            ファイルハンドル
  59.                        上位ワードが 非0 のとき:
  60.                            ファイル先頭部(2Kbyte以上)を読み込んだバッファへの
  61.                            FARポインタ
  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 FAR PASCAL GetPictureInfo(
  79.          LPSTR buf,long len,unsigned int flag,struct PictureInfo FAR *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 FAR *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.                     HGLOBAL hInfo;    画像内のテキスト情報
  100.                   };
  101.                   hInfoには必要に応じてPlug-inが確保したGlobalメモリーの
  102.                   ハンドルが格納される。
  103.  
  104.     Return:
  105.       エラーコード。0なら正常終了。
  106.  
  107.   ・GetPicture - 画像を展開する
  108.     Prototype:
  109.       extern "C" int _export FAR PASCAL GetPicture(
  110.               LPSTR buf,long len,unsigned int flag,
  111.               HANDLE FAR *pHBInfo,HANDLE FAR *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.       HGLOBAL FAR *pHBm    : ビットマップデータ本体のメモリハンドルが返される
  124.       HGLOBAL FAR *pHBInfo : BITMAPINFO 構造体が納められたメモリハンドルが
  125.                              返される。
  126.       FARPROC lpPrgressCallback :
  127.                 途中経過を表示するコールバック関数へのポインタ。
  128.                 MakeProcInstance を用いて求める。
  129.                 NULLの場合、plug-inは処理が終了するまでプロセスを占有し、
  130.                 中断も出来ません。
  131.                 コールバック関数のprototype:
  132.                   int FAR PASCAL ProgressCallback(
  133.                                         int nNum,int nDenom,long lData);
  134.                   まず nNum==0 でコールされ、nNum==nDenom になるまで
  135.                   定期的に呼ばれる。
  136.                   戻値が 非0 の時、Plug-inは処理を中断する。
  137.       long lData : コールバック関数に渡すlongデータ。
  138.                   FARポインタ等を必要に応じて受け渡せる。
  139.  
  140.     Return:
  141.       エラーコード。0なら正常終了。
  142.  
  143.  
  144.   ・GetPreview - プレビュー・カタログ表示用画像縮小展開ルーティン
  145.     Prototype:
  146.       extern "C" int _export FAR PASCAL GetPreview(
  147.               LPSTR buf,long len,unsigned int flag,
  148.               HANDLE FAR *pHBInfo,HANDLE FAR *pHBm,
  149.               FARPROC lpPrgressCallback,long lData);
  150.  
  151.     Parameter:
  152.       GETPICTURE参照。
  153.  
  154.     Return:
  155.       エラーコード。0なら正常終了。
  156.       この関数はオプションであり、未対応の場合は -1 を返す。
  157.  
  158.     解説:
  159.       プレビュー等で用いる縮小された画像をファイルから作成する。
  160.       JPEGの様に、アルゴリズムの関係で縮小されたサイズでは高速に展開出来る
  161.       ときにこの関数をインプリメントする。
  162.       今回配布のPlug-inでは IFJPEG.PLG のみ対応(1/4サイズで展開)している。
  163.       未対応の場合、Susieは通常の展開ルーティンを用いて展開した後
  164.       縮小処理を行う。
  165.       （対応していても縮小ロードされた画像を更にサイズ調整している）
  166.  
  167.   ・エラーコード
  168.     0 : 正常終了
  169.    -1 : その機能はインプリメントされていない
  170.     1 : コールバック関数が非0を返したので展開を中止した
  171.     2 : 未知のフォーマット
  172.     3 : データが壊れている
  173.     4 : メモリーが確保出来ない
  174.     5 : メモリーエラー（Lock出来ない、等）
  175.     6 : ファイルリードエラー
  176.     7 : （予約）
  177.     8 : 内部エラー
  178.  
  179. ５．'00AM'の関数 (暫定)
  180.  
  181.   ・IsSupported - 展開可能な(対応している)ファイル形式か調べる。
  182.     Prototype:
  183.       extern "C" int _export FAR PASCAL IsSupported(LPSTR filename,DWORD dw);
  184.  
  185.     Parameter:
  186.       LPSTR filename : ファイルネーム
  187.       DWORD dw       : 上位ワードが  0  のとき:
  188.                            ファイルハンドル
  189.                        上位ワードが 非0 のとき:
  190.                            ファイル先頭部(2Kbyte以上)を読み込んだバッファへの
  191.                            FARポインタ
  192.                            ファイルサイズが2Kbyte以下の場合もバッファは2Kbyte
  193.                            確保し、余分は 0 で埋めること
  194.  
  195.     Return:
  196.       対応している画像フォーマットであれば非0を返す
  197.  
  198.     解説:
  199.       詳しくは'00IN'のISSUPPORTED関数を参照の事。
  200.       引数dwで渡すバッファサイズ2Kbyte以上は自己解凍型LHa対応のため。
  201.  
  202.   ・GetArchiveInfo - アーカイブ内のすべてのファイルの情報を取得する
  203.     Prototype:
  204.       extern "C" errcode _export FAR PASCAL GetArchiveInfo(LPSTR buf,long len,
  205.             unsigned int flag,HGLOBAL FAR *lphInf);
  206.  
  207.     Parameter:
  208.       LPSTR buf : 入力がファイルの場合 ファイル名
  209.                         メモリーの場合 ファイルイメージへのポインタ
  210.       long len  : 入力がファイルの場合 読込み開始オフセット(MacBin対応のため)
  211.                         メモリーの場合 データサイズ
  212.       unsigned int flag : 追加情報 xxxx xxxx xxxx xSSS
  213.                   SSS : 入力形式
  214.                         0 : ディスクファイル
  215.                         1 : メモリ上のイメージ
  216.       HGLOBAL FAR *lphInf
  217.                 : ファイル情報の入ったハンドルを受け取る変数へのポインタ。
  218.                   Plug-in内で確保されたGLOBALメモリーに次の構造体配列が
  219.                   書き込まれ、そのハンドルが返される。
  220.                   method[0]=='\0'で終端。
  221.                         typedef struct
  222.                         {
  223.                             unsigned char method[8];    圧縮法の種類
  224.                             unsigned long position;     ファイル上での位置
  225.                             unsigned long compsize;     圧縮されたサイズ
  226.                             unsigned long filesize;     元のファイルサイズ
  227.                             time_t timestamp;           ファイルの更新日時
  228.                             char path[200];             相対パス
  229.                             char filename[200];         ファイルネーム
  230.                             unsigned long crc;         CRC
  231.                         } fileInfo;
  232.  
  233.     Return:
  234.       エラーコード。0なら正常終了。
  235.  
  236.   ・GetFileInfo - アーカイブ内の指定したファイルの情報を取得する
  237.     Prototype:
  238.       extern "C" errcode _export FAR PASCAL GetFileInfo(LPSTR buf,long len,
  239.                     LPSTR filename, unsigned int flag,fileInfo FAR *lpInfo);
  240.     Parameter:
  241.       LPSTR buf : 入力がファイルの場合 ファイル名
  242.                         メモリーの場合 ファイルイメージへのポインタ
  243.       long len  : 入力がファイルの場合 読込み開始オフセット(MacBin対応のため)
  244.                         メモリーの場合 データサイズ
  245.       LPSTR filename : 情報を取得するファイルのファイルネーム
  246.                         アーカイブ内の相対パスを含めて指定
  247.       unsigned int flag : 追加情報 xxxx xxxx Ixxx xSSS
  248.                   SSS : 入力形式
  249.                         0 : ディスクファイル
  250.                         1 : メモリ上のイメージ
  251.                   I : 0 : ファイル名の大文字小文字を区別する
  252.                       1 : ファイル名の大文字小文字を同一視する。
  253.       fileInfo FAR *lpInfo
  254.                 : 情報を受け取るfileInfo構造体へのポインタ
  255.  
  256.     Return:
  257.       エラーコード。0なら正常終了。
  258.  
  259.   ・GetFile - アーカイブ内のファイルを取得する
  260.     Prototype:
  261.       extern "C" errcode _export FAR PASCAL GetFile(LPSTR src,long len,
  262.                 LPSTR dest,unsigned int flag,
  263.                 FARPROC prgressCallback,long lData);
  264.  
  265.     Parameter:
  266.       LPSTR src  : 入力がファイルの場合 ファイル名
  267.                         メモリーの場合 ファイルイメージへのポインタ
  268.       long len   : 入力がファイルの場合 読込み開始オフセット
  269.                         メモリーの場合 データサイズ
  270.       void far *dest : 出力先がファイルの場合
  271.                               出力先ディレクトリ (相対パスは無視される)
  272.                         メモリーの場合 
  273.                               ファイルの入ったGLOBALメモリーハンドルを受け取る
  274.                               変数へのポインタ。
  275.       unsigned int flag  : 追加情報 xxxx xDDD xxxx xSSS
  276.                   SSS : 入力形式
  277.                         0 : ディスクファイル
  278.                         1 : メモリ上のイメージ
  279.                   DDD : 出力形式
  280.                         0 : ディスクファイル
  281.                         1 : メモリ上のイメージ
  282.       FARPROC lpPrgressCallback :
  283.                 途中経過を表示するコールバック関数へのポインタ。
  284.                 MakeProcInstance を用いて求める。
  285.                 NULLの場合、plug-inは処理が終了するまでプロセスを占有し、
  286.                 中断も出来ません。
  287.                 コールバック関数のprototype:
  288.                   int FAR PASCAL ProgressCallback(
  289.                                         int nNum,int nDenom,long lData);
  290.                   まず nNum==0 でコールされ、nNum==nDenom になるまで
  291.                   定期的に呼ばれる。
  292.                   戻値が 非0 の時、Plug-inは処理を中断する。
  293.       long lData : コールバック関数に渡すlongデータ。
  294.                   FARポインタ等を必要に応じて受け渡せる。
  295.  
  296.     Return:
  297.       エラーコード。0なら正常終了。
  298.  
  299. ６．Plug-inの使い方
  300.   Plug-inはDLLですから、通常のDLLと同じ用に次の２つの方法でアプリケーションに
  301.   リンク出来ます。
  302.  
  303.   1) DLLからインポートライブラリを作ってリンクする
  304.     implib.exe や implibw.exe を使ってPlug-inからインポートライブラリを
  305.     作って、これをアプリケーションにリンクします。
  306.     この方法は簡単ですが、特定のPlug-inしか使えません。
  307.   2) LoadLibrary で必要に応じてリンクする。
  308.     この方法は少々手間がかかりますが、検索して見つかったPlug-inを動的に
  309.     用いることができます。
  310.  
  311.   通常は1)の方法が用いられますが、複数のフォーマットに対応する必要がある
  312.   場合には2)の方法をおすすめします。
  313.   2)の方法を用いるものとして全体の流れを説明します。
  314.  
  315.   1.Plug-inを検索する。
  316.     Plug-inのあるディレクトリを"*.plg"で検索し、見つかったものを
  317.     LoadLibrary でロードします。
  318.     GetProcAddress で GETPLUGININFO 関数へのポインタを取得し、
  319.     GETPLUGININFO 関数にて情報番号0のPlug-inバージョンを確かめます。
  320.     対応しているバージョンならPlug-inリストに加えます。
  321.     対応していないものならFreeLibraryで忘れずに開放します。
  322.  
  323.   2.画像ファイルに合ったPlug-inを探す。
  324.     画像ファイルをロードする必要が生じたならまずそのファイルを_lopen等で
  325.     オープンします。
  326.     次に Plug-inリストにしたがって順に ISSUPPORTED 関数を呼び、対応した
  327.     Plug-inを探します。MacBinary が付いている可能性があるので、offset=0で
  328.     だめな場合は offset=128 でもう一度探すと良いでしょう。
  329.  
  330.   3.画像を展開する。
  331.     対応したPlug-inが見つかったらそのPlug-inの GETPICTURE 関数でロードします。
  332.     この時、CALLBACK関数を用意出来るなら MakeProcInstance にてFARポインタを
  333.     取得し、GETPICTURE 関数に渡します。
  334.     CALLBACK関数内で PeekMessage を使う事で他のプロセスに(そして自分にも)
  335.     実行の機会を与えるとスマートです。
  336.  
  337.   4.Plug-inを開放する。
  338.     アプリケーションを終了する時には忘れずに LoadLibrary したPlug-inすべてを
  339.     FreeLibrary で開放しましょう。
  340.  
  341.  
  342. ７．Plug-inの仕様と使用に関して
  343.   Plug-inを作りたい、もしくは使いたいがこれではよくわからん、という方は
  344.   下記IDまでお問い合わせ下さい。なにかしら助言出来ると思います。（返事が
  345.   遅くなっても怒らないでね(^_^;)）
  346.   また、APIの仕様に関しての御意見もお待ちしております。APIバージョンアップ時
  347.   に参考にさせていただきます。このバージョンは Susie の内部クラスのI/Fの
  348.   ほとんどそのままなので汎用性に欠けますし(^_^;)
  349.   転載等に関しては plugin.txt を参照して下さい。
  350.  
  351.     東京BBS     TAKECHIN
  352.     Nifty-serve GGB01506   竹村嘉人 (たけちん)
  353.