F2PCV.DLL インターフェース


#include "f2pcvif.h"

T_F2PIF *f2pcv_dllmain( T_F2PIF *TP_INDATA );
T_F2PIF *f2pcv_dllfreem( T_F2PIF *TP_INDATA );


機能

 f2pcv_dllmain関数は、与えられたFMPデータをもとにPMDデータを生成する関数である。この関数はインターフェース構造体の設定値通りに処理を行い、バッファを動的に確保してMML等出力文字列を格納し、それぞれのバッファアドレスをインターフェース構造体に格納し処理を返す。

 f2pcv_dllfreem関数は、f2pcv_dllmain関数にて確保したバッファを一括して開放する。同一アプリケーションから複数回f2pcv_dllmain関数をコールする場合に使用する。

 なお当プログラムは、PMDRC.DLLにてMMLを生成するためにFMPデータをPMD形式にコンバートするものであり、FMPデータをPMDデータにコンバートして保存するものではないことを明記しておく(聴くだけならばWinFMP.DLLを使用すべきだ)
 実装レベルの話をすると、F2PCV.DLLは読み込まれたFMPデータの中から、PMDRC.DLLの定義する「レベル4(PMDRC.DLLの説明を参照のこと)」のデータのみをピックアップし、PMDデータとして出力する。よって、音色番号を始めとした「音程・音長に影響のないMML」を出力しない。

引数 TP_INDATA

 各関数へ渡すインターフェース構造体のアドレス。

戻り値

 f2pcv_dllmain関数は、正常に処理が行われたとき、引数で指定されたアドレスが戻る。ここでいう「正常」には、「データエラーを正常に処理した」場合も含まれる。実行結果そのものは、構造体内部の変数 i_result を参照すること。
 処理が異常に終わったとき、NULLポインタが戻る。

 f2pcv_dllfreem関数は、常に引数と同じアドレスが返される。
 以下に、引数で与えるべき構造体の型「T_OPIF」の内容を示す。

変数名 方向 内容
i_iv 入出力 int インターフェースバージョンを記述する。アプリケーション側で指定したインターフェースバージョンがライブラリ側と一致しない場合、エラーとなる。
i_directmes 入力 int 0,1 DLL内部での制御メッセージを、標準エラー出力にリアルタイム出力するかしないかを指定する。呼び出し元のアプリケーションがコマンドラインプログラムである場合に使う。設定値は以下の通り。
0:DA_OFF:出力しない
1:DA_ON:出力する
ただし、どちらの設定でも、メッセージ出力バッファ(cps_out[0])には書き込まれる。
i_datatype 入出力 int 0,2,3,4 データファイルのタイプ(OPI/OVI/OZI)をセットする。DLLも、解析が終わり次第差異があればこのパラメータを変更する。
0:D_TYPE_UK:不明 2:D_TYPE_OPI:パート数が6であるデータ。 3:D_TYPE_OVI:パート数が11であるデータ。 4:D_TYPE_OZI:PPZ対応データ。パート数は不問。
i_result 出力 int ライブラリが実行結果を記述する。結果の内容は以下の通り。
0 DR_NORMAL 正常終了。
-1 DR_E_FATALERROR 致命的なロジックエラー。
-2 DR_E_NEIFVERSION インターフェースバージョンが一致しない。
-3 DR_E_NSAPVERSION アプリケーションバージョンがサポート外。
-4 DR_E_NGIF インターフェース内容が正しくない。
-5 DR_E_BADDATA FMPデータ内にエラーが存在する。
-6 DR_E_NSDTVERSION FMPデータバージョンがサポート外。
-7 DR_E_SHORTBUF バッファが不足している内部エラー。
1 DR_W_BADMML 出力データが正しくない(正しく解析できなかった)。
cp_indata 入力 char * アドレス 解析を行うFMPデータのアドレスを指定する。PMDデータはメモリ上に展開されたもので、終端は設けない(ライブラリはデータの終端をPMDデータ内部情報から特定する)。データフォーマットが壊れている場合及びDLLが未対応のデータをここに指定した場合、アプリケーションは異常終了する(DLLで保護はしていない)。
cp_debugdata 入力 char * アドレス 通常はNULLを必ず指定する。
当ポインタがNULLでない場合、当該アドレスから文字列と認識し、指定文字列をファイル名とする変換後PMDデータを出力する。このPMDデータはPMDRC.DLLで逆コンパイルする以外の目的に使用することは勧めない。PMDRC.DLLで認識しない部分はダミーデータが詰まっているため、PMDで演奏するのは危険。
cp_outdata 出力 char * アドレス FMPデータから変換し出力するPMDデータの先頭アドレスが示される。cp_debugdataをファイル名とするファイルの内容と同一である。
i_directmes 出力 int DLL内部での制御メッセージを、標準エラー出力にリアルタイム出力するかしないかを指定する。呼び出し元のアプリケーションがコマンドラインプログラムである場合に使う。設定値は以下の通り。
0:DA_OFF:出力しない
1:DA_ON:出力する
ただし、どちらの設定でも、メッセージ出力バッファ(cps_out[0])には書き込まれる。
cps_out[0] 出力 char * 文字列 ライブラリにより、実行時メッセージ出力バッファアドレスが設定される。NULLの場合は、当該バッファにデータが出力されていないことを示す(通常、一部のインターフェースエラー発生時等を除き、処理の正常・異常を問わず、必ず出力される)。
使用後、このアドレスは pmdrc_dllfreem( ) にて解放する必要がある。