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