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