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