FMP7 公開API仕様

FMP7の制御を行うためのAPI及び、公開ワークについての資料です。

FMP7はDLLとして提供されないため、自作のアプリケーションから制御を行なう場合はSendMessageにて制御指令を送ります。
また、公開ワークも別プロセスとして動作しているためアプリケーション内のメモリ上ではなく、共有メモリを介してアクセスを行なう必要があります。

制御メッセージは、FMP7に対して制御を行う場合や、演奏中に変化しない情報の取得要求などを行う際に利用します。
公開ワークは、主に演奏に関するデータの取得を行う際に利用します。

制御メッセージ

FMP7へはWM_COPYDATAメッセージを利用してコマンドの送信を行います。
必要なパラメータ情報は「COPYDATASTRUCT」構造体に値を設定します。
基本的にはdwDataのLOWORDがファンクション番号となり、APIによってはHIWORDにサブパラメータをセットします。
文字列はすべてWCHARの扱いとなります。

公開ワーク

公開ワークは共有メモリとして提供されます。
共有メモリの構造はfmp32_sharework.hを参考にして下さい。
共有メモリは読み込み専用としてアクセスを行ってください。

#include "fmp32_sharework.h"

HANDLE hFileMap;
HANDLE hMutex;
FMP32::FUNC* hFMP7;
int SizeGlobal, SizePart, SizeEx;
BYTE *pWork;
PFMP32_GLOBALWORK pGlobal;
PFMP32_PARTWORK* pPart;
PFMP32_EXWORK* pEx;

void Init() {
    // 共有メモリサイズ取得
    hFMP7 = GetFMP7Instance();
    if(! hFMP7->GetWorkSize(&SizeGlobal, &SizePart, &SizeEx))
        return;

    // 共有メモリハンドル取得
    hFileMap = OpenFileMapping(FILE_MAP_READ, FALSE, FMP32_KEY_MAP);
    if(hFileMap == NULL)
        return;

    // 共有メモリmutex取得
    hMutex = OpenMutex(SYNCHRONIZE, FALSE, FMP32_KEY_MUTEX);
    if(hMutex == NULL)
        return;

    // ワーク確保
    pWork = new BYTE[SizeGlobal +(SizePart +SizeEx) *FMP32_MAX_PART];
    if(pWork == NULL)
        return;
    pGlobal = (PFMP32_GLOBALWORK)pWork;
    pPart = (PFMP32_PARTWORK*) new PFMP32_PARTWORK[FMP32_MAX_PART];
    pEx = (PFMP32_EXWORK*) new PFMP32_EXWORK[FMP32_MAX_PART];
    // ワークアドレスマッピング
    for(int n = 0; n < FMP32_MAX_PART; n++) {
        pPart[n] = (PFMP32_PARTWORK)&pWork[SizeGlobal +SizePart*n];
        pEx[n] = (PFMP32_EXWORK)&pWork[SizeGlobal +SizePart*FMP32_MAX_PART +SizeEx*n];
    }
}

void Access() {
    // 同期待ち
    WaitForSingleObject(hMutex, INFINITE);

    BYTE* p = (BYTE*)MapViewOfFile(hFileMap,
                                   FILE_MAP_READ,
                                   0,
                                   0,
                                   SizeGlobal +(SizePart +SizeEx)*FMP32_MAX_PART);

    // ワークアクセス
    // mutexのロックを行っているため、この状態を長時間維持しないこと。
    // ロックをしている間はデータの更新が行われなくなる。
    // また、mutexのロックを行わずにアクセスを行った場合は、データの整合性の保証はされない。
    CopyMemory(pWork, p, SizeGlobal +(SizePart +SizeEx) *FMP32_MAX_PART);

    // マップ解放
    UnmapViewOfFile(p);
    // mutex解放
    ReleaseMutex(hMutex);

    // コピーしたワークに対して処理を実行
    for(int n = 0; n < FMP32_MAX_PART; n++) {
        switch(pPart[n]->Mode) {
          case FMP32_MODE_FM:
            if(pPart[n]->State & FMP32_BIT_PLAY) {
                :
            }
            :
            break;
          case FMP32_MODE_SSG:
            :
            break;
        }
    }
}

void Term() {
    CloseHandle(hMutex);
    CloseHandle(hFileMap);
    delete [] pWork;
    delete [] pPart;
    delete [] pEx;
}

#include "fmp32_sharework.h"

HANDLE hFileMap;

HANDLE hMutex;

FMP32::FUNC* hFMP7;

int SizeGlobal, SizePart, SizeEx;

BYTE *pWork;

PFMP32_GLOBALWORK pGlobal;

PFMP32_PARTWORK* pPart;

PFMP32_EXWORK* pEx;

void Init() {

// 共有メモリサイズ取得

hFMP7 = GetFMP7Instance();

if(! hFMP7->GetWorkSize(&SizeGlobal, &SizePart, &SizeEx))

return;

// 共有メモリハンドル取得

hFileMap = OpenFileMapping(FILE_MAP_READ, FALSE, FMP32_KEY_MAP);

if(hFileMap == NULL)

return;

// 共有メモリmutex取得

hMutex = OpenMutex(SYNCHRONIZE, FALSE, FMP32_KEY_MUTEX);

if(hMutex == NULL)

return;

// ワーク確保

pWork = new BYTE[SizeGlobal +(SizePart +SizeEx) *FMP32_MAX_PART];

if(pWork == NULL)

return;

pGlobal = (PFMP32_GLOBALWORK)pWork;

pPart = (PFMP32_PARTWORK*) new PFMP32_PARTWORK[FMP32_MAX_PART];

pEx = (PFMP32_EXWORK*) new PFMP32_EXWORK[FMP32_MAX_PART];

// ワークアドレスマッピング

for(int n = 0; n < FMP32_MAX_PART; n++) {

pPart[n] = (PFMP32_PARTWORK)&pWork[SizeGlobal +SizePart*n];

pEx[n] = (PFMP32_EXWORK)&pWork[SizeGlobal +SizePart*FMP32_MAX_PART +SizeEx*n];

}

void Access() {

// 同期待ち

WaitForSingleObject(hMutex, INFINITE);

BYTE* p = (BYTE*)MapViewOfFile(hFileMap,

FILE_MAP_READ,

SizeGlobal +(SizePart +SizeEx)*FMP32_MAX_PART);

// ワークアクセス

// mutexのロックを行っているため、この状態を長時間維持しないこと。

// ロックをしている間はデータの更新が行われなくなる。

// また、mutexのロックを行わずにアクセスを行った場合は、データの整合性の保証はされない。

CopyMemory(pWork, p, SizeGlobal +(SizePart +SizeEx) *FMP32_MAX_PART);

// マップ解放

UnmapViewOfFile(p);

// mutex解放

ReleaseMutex(hMutex);

// コピーしたワークに対して処理を実行

for(int n = 0; n < FMP32_MAX_PART; n++) {

switch(pPart[n]->Mode) {

case FMP32_MODE_FM:

if(pPart[n]->State & FMP32_BIT_PLAY) {

}

break;

case FMP32_MODE_SSG:

break;

}

void Term() {

CloseHandle(hMutex);

CloseHandle(hFileMap);

delete [] pWork;

delete [] pPart;

delete [] pEx;

}

ブロードキャストメッセージ

FMP7の起動時及び終了時にはブロードキャストメッセージが送信されます。
公開ワークを参照する場合には、本メッセージを処理し、公開ワークアドレスの再取得などするようにして下さい。

#include "fmp32_api.h"

UINT MessageBC;

// ブロードキャストメッセージコード取得
if(0 == (MessageBC = RegisterWindowMessage(FMP32::MESSAGE::REGISTER_STRING)))
    return(FALSE);

#include "fmp32_api.h"

UINT MessageBC;

// ブロードキャストメッセージコード取得

if(0 == (MessageBC = RegisterWindowMessage(FMP32::MESSAGE::REGISTER_STRING)))

return(FALSE);

取得したメッセージは通常のメッセージハンドラ中で他のメッセージ同様に処理を行います。

LRESULT CALLBACK
WndProc(
    HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam
) {
    switch(message) {
        :
      default:
        if(message == MessageBC) {
            switch(wParam) {
              case FMP32::MESSAGE::START_FMP:
                // FMP7起動時の処理(共有メモリ情報の再初期化など)
                ReInitWork();
                :
                return(0);
              case FMP32::MESSAGE::END_FMP:
                // FMP7終了時の処理
                :
                return(0);
            }
        }
        return(DefWindowProc(hWnd, message, wParam, lParam));
    }
    return(0);
}

LRESULT CALLBACK

WndProc(

HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam

) {

switch(message) {

default:

if(message == MessageBC) {

switch(wParam) {

case FMP32::MESSAGE::START_FMP:

// FMP7起動時の処理(共有メモリ情報の再初期化など)

ReInitWork();

return(0);

case FMP32::MESSAGE::END_FMP:

// FMP7終了時の処理

return(0);

}

return(DefWindowProc(hWnd, message, wParam, lParam));

}

return(0);

}

制御クラス

直接SendMessageにて送る手段の他に、C++からのアクセスインタフェースとしてFMP32クラスが提供されます。
クラスが利用可能な環境では、制御が簡略されます。

#include "fmp32_api.h"

// FMP7制御ライブラリ
#pragma comment (lib, "FMP7_lib.lib")

// ライブラリ初期化
FMP32::FUNC* hFMP7;
hFMP7 = GetFMP7Instance();

// 曲読み込み
hFMP7->MusicLoad("ファイル名");

#include "fmp32_api.h"

// FMP7制御ライブラリ

#pragma comment (lib, "FMP7_lib.lib")

// ライブラリ初期化

FMP32::FUNC* hFMP7;

hFMP7 = GetFMP7Instance();

// 曲読み込み

hFMP7->MusicLoad("ファイル名");

fmp32_api.hにて定義されているのPUBLICメソッドの一覧を説明します。
FMP7の制御はなるべく本クラスを利用して行って下さい。
独自に実装を行った場合の動作の保証は出来ません。

演奏データ読み込み

指定されたファイルを読み込みます。演奏は開始されません。

書式

BOOL MusicLoad(
    LPWSTR filename
);

パラメータ

filename
ファイル名を指定します。

戻り値

正常に処理が終了した場合は0以外の値が返ります。
エラーの場合の詳細はGetLastError()にて取得します。

演奏データ読み込み演奏

指定されたファイルを読み込みます。演奏を開始します。

書式

BOOL MusicPlay(
    LPWSTR filename
);

パラメータ

filename
ファイル名を指定します。

戻り値

正常に処理が終了した場合は0以外の値が返ります。
エラーの場合の詳細はGetLastError()にて取得します。

演奏開始

演奏を開始します。既に演奏中の場合には、曲の最初から演奏が始まります。

書式

BOOL MusicPlay(
    void
);

書式

BOOL SetMask(
    int part
    BOOL mask
);

パラメータ

part
パート番号を0～63で指定します。
mask
マスクの有効・無効を指定します。

戻り値

正常に処理が終了した場合は0以外の値が返ります。
エラーの場合の詳細はGetLastError()にて取得します。

パートマスク指定（一括）

パートのマスクを指定します。マスクデータは「1」でマスク指定「0」でマスク解除となります。
パート番号65以降は現在では意味を持ちませんが、必ず指定が必要です。

書式

BOOL SetMask(
    BYTE* mask
);

パラメータ

mask
パート毎のマスクの指定が記述されたBYTE[128]の配列のポインタを指定します。
配列のサイズは必ず128必要です。

戻り値

正常に処理が終了した場合は0以外の値が返ります。
エラーの場合の詳細はGetLastError()にて取得します。

シーク位置指定

演奏中のシーク位置を演奏開始からのカウント数で指定します。

書式

BOOL SetSeek(
    DWORD count
);

パラメータ

count
演奏位置をカウント数で指定します。

戻り値

正常に処理が終了した場合は0以外の値が返ります。
エラーの場合の詳細はGetLastError()にて取得します。

バージョン取得

FMP7のバージョンを取得します。メジャーバージョンが同一の間は基本的に動作の互換性は保証されます。

書式

BOOL GetVersion(
    int* system,
    int* major,
    int* minor
);

パラメータ

system
システムバージョンが格納されるint型のポインタを指定します。NULLが指定された場合はパラメータは無視されます。
FMP7では「7」固定です。
major
メジャーバージョンが格納されるint型のポインタを指定します。NULLが指定された場合はパラメータは無視されます。
0～99の数値で表され、数値が１つ上がるとワーク/APIなどに変更がされたことになります。
minor
マイナーバージョンが格納されるint型のポインタを指定します。NULLが指定された場合はパラメータは無視されます。
キャラクタコード1byteで表されます。
内部的な変更があった場合に変化します。

戻り値

正常に処理が終了した場合は0以外の値が返ります。
エラーの場合の詳細はGetLastError()にて取得します。

ワークサイズ取得

FMP7の公開共有ワークのサイズを取得します。

書式

BOOL GetWorkSize(
    int* global,
    int* part,
    int* ex
);

パラメータ

global
グローバルワークのサイズが格納されるint型のポインタを指定します。NULLが指定された場合はパラメータは無視されます。
サイズはBYTEです。
part
パートワークのサイズが格納されるint型のポインタを指定します。NULLが指定された場合はパラメータは無視されます。
サイズはBYTEです。１パート分のワークサイズとなり、全部で64パート並びます。
ex
拡張情報ワークのサイズが格納されるint型のポインタを指定します。NULLが指定された場合はパラメータは無視されます。
サイズはBYTEです。

戻り値

正常に処理が終了した場合は0以外の値が返ります。
エラーの場合の詳細はGetLastError()にて取得します。

演奏ファイルパス取得

現在読み込まれている演奏ファイルのフルパスを取得します。

書式

int GetPlayFilename(
    LPWSTR filename,
    int maxlen
);

パラメータ

filename
フィル名を格納するWCHAR型バッファのポインタを指定します。バッファサイズが足らない場合はエラーとなり、filenameの値は不定となります。
NULLを指定することでfilenameのセットはされず、文字数だけを取得出来ます。
maxlen
バッファの大きさを文字数で指定します。

戻り値

正常に処理が終了した場合は文字数が返ります。
エラーの場合は-1が返り、詳細はGetLastError()にて取得します。

曲タイトル取得

読み込まれているデータのタイトル名を取得します。

書式

int GetMusicTitle(
    LPWSTR title,
    int maxlen
);

パラメータ

title
タイトル名を格納するWCHAR型バッファのポインタを指定します。バッファサイズが足らない場合はエラーとなり、途中までの情報が返されます。
NULLを指定することでtitleのセットはされず、文字数だけを取得出来ます。
maxlen
バッファの大きさを文字数で指定します。

戻り値

正常に処理が終了した場合は文字数が返ります。
エラーの場合は-1が返り、詳細はGetLastError()にて取得します。

曲製作者名取得

読み込まれているデータの製作者名を取得します。

書式

int GetMusicCreator(
    LPWSTR name,
    int maxlen
);

パラメータ

name
製作者名を格納するWCHAR型バッファのポインタを指定します。バッファサイズが足らない場合はエラーとなり、途中までの情報が返されます。
NULLを指定することでnameのセットはされず、文字数だけを取得出来ます。
maxlen
バッファの大きさを文字数で指定します。

戻り値

正常に処理が終了した場合は文字数が返ります。
エラーの場合は-1が返り、詳細はGetLastError()にて取得します。

曲作曲者名取得

読み込まれているデータの作曲者名を取得します。

書式

int GetMusicComposer(
    LPWSTR name,
    int maxlen
);

パラメータ

name
作曲者名を格納するWCHAR型バッファのポインタを指定します。バッファサイズが足らない場合はエラーとなり、途中までの情報が返されます。
NULLを指定することでnameのセットはされず、文字数だけを取得出来ます。
maxlen
バッファの大きさを文字数で指定します。

戻り値

正常に処理が終了した場合は文字数が返ります。
エラーの場合は-1が返り、詳細はGetLastError()にて取得します。

曲コメント取得

読み込まれているデータのコメントを取得します。

書式

int GetMusicComment(
    LPWSTR comment,
    int maxlen
);

パラメータ

comment
コメントを格納するWCHAR型バッファのポインタを指定します。バッファサイズが足らない場合はエラーとなり、途中までの情報が返されます。
NULLを指定することでcommentのセットはされず、文字数だけを取得出来ます。
maxlen
バッファの大きさを文字数で指定します。

戻り値

正常に処理が終了した場合は文字数が返ります。
エラーの場合は-1が返り、詳細はGetLastError()にて取得します。

演奏データ拡張子リスト取得

受付可能なデータ拡張子のリストを返します。
addonドライバを含めたすべてのデータの情報が取得可能です。

書式

int GetExtList(
    LPWSTR text,
    int maxlen,
    BOOL filter
);

パラメータ

text
リストを格納するWCHAR型バッファのポインタを指定します。バッファサイズが足らない場合はエラーとなり、textの値は不定となります。
NULLを指定することでtextのセットはされず、文字数だけを取得出来ます。
maxlen
バッファの大きさを文字数で指定します。
filter
OPENFILENAME構造体で利用可能な形式に変換を行うかを指定します。

戻り値

正常に処理が終了した場合は文字数が返ります。
エラーの場合は-1が返り、詳細はGetLastError()にて取得します。

リスト構造

拡張子リストは以下のテキスト形式となります。

対応ドライバ名１|*.拡張子１(;*.拡張子２...) (,対応ドライバ名２|*.拡張子１(;*.拡張子２...) ...)

ただし、filterに「TRUE」が指定された場合は以下の形式となります。

対応ドライバ (*.拡張子１(/*.拡張子２...))*.拡張子１(;*.拡張子２...)¥0
 :
対応ドライバ (*.拡張子１(/*.拡張子２...))*.拡張子１(;*.拡張子２...)¥0
¥0

エラーコード取得

エラー発生時の内部エラーコードを返します。

書式

DWORD GetLastError(
    void
);

パラメータ

なし

戻り値

最後に発生したエラーコードを返します。

エラーメッセージ取得

エラー発生時のコードに対する内部メッセージを返します。

書式

int GetErrorMessage(
    LPWSTR text,
    int maxlen
);

パラメータ

text
エラーメッセージを格納するWCHAR型バッファのポインタを指定します。バッファサイズが足らない場合はエラーとなり、途中までの情報が返されます。
NULLを指定することでtextのセットはされず、文字数だけを取得出来ます。
maxlen
バッファの大きさを文字数で指定します。

戻り値

文字数が返ります。

Comments are closed.