DoctorMX ライブラリー(Windows 用)
DoctorMX USB/DMX512 インターフェースハードウェアを使用するためのライブラリーです。
デバイスドライバーを使用するので、DoctorMX のインストーラーをあらかじめ実行しておいて下さい。
include
DDrMXLib.h
C/C++ 用インクルードファイルです。
DDrMXLib.bas
VisualBasic 用インクルードファイルです。
(注:VisualBasic での動作は確認されておりません。
不具合がありましたらお知らせ下さい)
sample
DrMXLibTest.cpp
テストアプリケーションのソースファイルです。
DrMXLTest.cpp
テストアプリケーションのソースファイルです。
x86、x64
drmxlib.dll
ダイナミックリンクライブラリーファイルです。
drmxlib.lib
インポートライブラリーファイルです。
開発環境のプロジェクトに使用します。
DrMXLibTest.exe
drmxlib.dll
を使用するテストアプリケーションです。
「コンソール」(「MSDOS プロンプト」)アプリケーションから実行して下さい。
DoctorMX USB/DMX512 インターフェースハードウェアの入出力をケーブルでつないでループしておくと、出力したデータと入力したデータを比較し、一致するかしないかを表示します。
DrMXLTest.exe
drmxlib.dll
を使用するテストアプリケーションです。
WM_TIMER
によって定期的に DrMX_Write()
を使用します。
ウインドウをクリックするたびに DrMX_Open()
と DrMX_Close()
を交互に使用します。
C/C++ API
装置の列挙
RDrMXEnum DrMXEnum_New();
利用できるインターフェースハードウェアを列挙する列挙子を作成します。
void DrMXEnum_Delete(RDrMXEnum aE);
列挙子の使用を終えます。
aE
DrMXEnum_New()
で返されたポインター。
BOOL WINAPI DrMXEnum_Next(RDrMXEnum aE, TCHAR aID[16]);
装置の識別子(文字列)を1つずつ返します。
これは個々のインターフェースハードウェアに固有のシリアル番号です。
(初期の製品の場合はシリアル番号がなく、この場合は USB 接続位置を示す固有の文字列で代用します)
装置がある場合(aID
に有効な識別子を返した場合)は TRUE
を返します。
装置がない場合は FALSE
を返します。
aE
DrMXEnum_New()
で返されたポインター。
aID
文字列を受け取る配列(少なくとも 16 文字分割り当てて下さい)。
文字列は NULL
終端されます。
シリアル番号は4桁の十進整数です。
(シリアル番号がない場合の代用文字列は8文字です)
装置の使用
RDrMX WINAPI DrMX_Open();
1つのインターフェースハードウェアの使用を始めます。
利用できる場合、インターフェースハードウェアへのポインター(参照)を返します。
ハードウェアが接続されていないなど、何らかの理由で利用できない場合は NULL
を返します。
VOID WINAPI DrMX_Close(RDrMX aR);
インターフェースハードウェアの使用を終えます。
aR
DrMX_Open()
で返されたポインター。
DWORD WINAPI DrMX_Write(RDrMX aR, const BYTE* aP, DWORD aL, DWORD aT);
DMX にデータを出力します。
DMX 信号を出力し続けるには、定期的に DrMX_Write()
を繰り返し使用します。
前回の DrMX_Write()
による出力が完了していない場合、タイムアウト値まで待ちます。
出力を開始すると DrMX_Write()
は終了し 1
を返します。
タイムアウトなどで出力を開始できない場合は 0
を返します。
タイムアウト以外にも、実行スレッドが未処理のメッセージを持っている場合など、出力を開始せずに 0
を返します。
タイムアウトの時間精度は実行するコンピューター環境により異なりますので目安程度として下さい。
aR
DrMX_Open()
で返されたポインタ。
aP
バイト配列へのポインター。
最初のバイト(aP[0]
)は DMX スタートコード(通常は 0)です。
aL
バイト配列の長さ。
最大 513 です。
aT
タイムアウト(mS 単位)。
DWORD WINAPI DrMX_Read(RDrMX aR, BYTE* aP, DWORD aL, DWORD aT);
DMX からのデータを読み込みます。
前回の DrMX_Read()
による読み込みが完了していない場合、タイムアウト値まで待ちます。
読み込みデータがある場合は DrMX_Read()
は終了し、読み込まれたバイト数を返します。
aL
で指定されたよりも多いデータは捨てられます。
タイムアウトなどで読み込みデータがない場合は 0
を返します。
タイムアウト以外にも、実行スレッドが未処理のメッセージを持っている場合など、読み込むことなく 0
を返します。
タイムアウトの時間精度は実行するコンピュータ環境により異なりますので目安程度として下さい。
aR
DrMX_Open()
で返されたポインター。
aP
読み込みバイト配列へのポインター。
最初のバイト(aP[0]
)は DMX スタートコード(通常は 0)になります。
aL
最大読み込みバイト数。
最大 513 です。
aT
タイムアウト(mS 単位)。
RDrMX WINAPI DrMX_OpenID(LPCTSTR aID);
特定のインターフェースハードウェアの使用を始めます。
利用できる場合、インターフェースハードウェアへのポインター(参照)を返します。
ハードウェアが接続されていないなど、何らかの理由で利用できない場合は NULL
を返します。
aID
DrMXEnum_Next()
で得られるインターフェースボックスの識別子(シリアル番号)。
文字列は NULL
終端です。
BOOL WINAPI DrMX_SetTiming(RDrMX aR, DWORD aBrk, DWORD aMAB, DWORD aMBS);
出力信号のタイミングを設定します。
ハードウェアが接続されていないなど、何らかの理由で設定できない場合は FALSE
を返します。
aBrk
ブレーク時間を設定します。
これは規格の最短値(92μS)に加える値を指定します。
デフォルトは「84」です(ブレーク時間は176μS)。
0〜255 [μS]の範囲のみ有効です。
aMAB
ブレーク後のマーク時間(Mark After Break)を設定します。
これは規格の最短値(12μS)に加える値を指定します。
デフォルトは「0」です(MAB時間は12μS)。
0〜255 [μS]の範囲のみ有効です。
aMBS
スロット間マーク時間(Mark Between Slot)を設定します。
デフォルトは「0」です(MBS時間は0μS)。
0〜255 [μS]の範囲のみ有効です。
使用例
TCHAR devid[16];
RDrMXEnum de = DrMXEnum_New();
while (DrMXEnum_Next(de, devid))
{
}
DrMXEnum_Delete(de);
/* ----------- */
BYTE wbuf[513];
BYTE rbuf[513];
DWORD r;
RDrMX drmx = DrMX_Open();
if (drmx != NULL)
{
/* setup output data
|
|
*/
r = DrMX_Write(drmx, wbuf, 513, 30);
if (r == 0)
{
/* retry later */
}
r = DrMX_Read(drmx, rbuf, 513, 30);
if (0 < r)
{
/* process input data */
}
DrMX_Close(drmx);
}
使用上の注意
DrMX_Write()
および DrMX_Read()
は、タイマー(WM_TIMER
) を使用して定期的に行うようにして下さい。
あるいは何らかの操作によって「出力フラグ」を立て、タイマで定期的にフラグをテストして必要なら出力する(そして成功したらフラグをクリア)ようにして下さい。
Windows では、タイマーは他に処理すべきメッセージがない場合に実行されますので、 DrMX_Write()
および DrMX_Read()
は通常成功します。
ライブラリーファイル中では
MsgWaitForMultipleObjectsEx(1, &aE, aT, QS_ALLPOSTMESSAGE | QS_ALLINPUT, MWMO_ALERTABLE | MWMO_INPUTAVAILABLE);
によって DMX 入/出力とメッセージキュー、タイムアウトを待ち、DMX 出力が可能になったとき(戻り値が WAIT_OBJECT_0
)出力開始します。
WM_TIMER
中でも、DrMX_Write()
および DrMX_Read()
を実行するまでにメッセージキューに新たにメッセージが追加されることもあり得ますのでご注意ください。
他に、DrMX_Write()
および DrMX_Read()
を別スレッドで実行することも考えられます。
DrMX_Read()
の戻り値が 0
以外の場合は繰り返し呼び出して下さい。
こうすると入力バッファーの内容をためることなく読み込めます。
VisualBasic API
詳細は上記の C/C++ API を参考にして下さい。
(注:VisualBasic での動作は確認されておりません。
不具合がありましたらお知らせ下さい)
Declare Function DrMXEnum_New Lib "drmxlib.dll" () As Long
Declare Sub DrMXEnum_Delete Lib "drmxlib.dll" (ByVal aR As Long)
Declare Function DrMXEnum_NextW Lib "drmxlib.dll" (ByVal aR As Long, ByRef aID As Integer) As Long
Declare Function DrMXEnum_NextA Lib "drmxlib.dll" (ByVal aR As Long, ByRef aID As Byte) As Long
Declare Function DrMX_Open Lib "drmxlib.dll" () As Long
Declare Sub DrMX_Close Lib "drmxlib.dll" (ByVal aR As Long)
Declare Function DrMX_Write Lib "drmxlib.dll" (ByVal aR As Long, ByRef aP As Byte, ByVal aL As Long, ByVal aT As Long) As Long
Declare Function DrMX_Read Lib "drmxlib.dll" (ByVal aR As Long, ByRef aP As Byte, ByVal aL As Long, ByVal aT As Long) As Long
Declare Function DrMX_OpenIDW Lib "drmxlib.dll" (ByRef aID As Integer) As Long
Declare Function DrMX_OpenIDA Lib "drmxlib.dll" (ByRef aID As Byte) As Long
お問い合わせ
メール(uty@kuwatec.co.jp)