DoctorMX ライブラリー(Windows 用)

DoctorMX USB/DMX512 インターフェースハードウェアを使用するためのライブラリーです。
デバイスドライバーを使用するので、DoctorMX のインストーラーをあらかじめ実行しておいて下さい。

C/C++ API


装置の列挙

RDrMXEnum DrMXEnum_New();
利用できるインターフェースハードウェアを列挙する列挙子を作成します。

void DrMXEnum_Delete(RDrMXEnum aE);
列挙子の使用を終えます。

BOOL WINAPI DrMXEnum_Next(RDrMXEnum aE, TCHAR aID[16]);
装置の識別子(文字列)を1つずつ返します。
これは個々のインターフェースハードウェアに固有のシリアル番号です。
(初期の製品の場合はシリアル番号がなく、この場合は USB 接続位置を示す固有の文字列で代用します)
装置がある場合(aID に有効な識別子を返した場合)は TRUE を返します。
装置がない場合は FALSE を返します。

装置の使用

RDrMX WINAPI DrMX_Open();
1つのインターフェースハードウェアの使用を始めます。
利用できる場合、インターフェースハードウェアへのポインター(参照)を返します。
ハードウェアが接続されていないなど、何らかの理由で利用できない場合は NULL を返します。

VOID WINAPI DrMX_Close(RDrMX aR);
インターフェースハードウェアの使用を終えます。

DWORD WINAPI DrMX_Write(RDrMX aR, const BYTE* aP, DWORD aL, DWORD aT);
DMX にデータを出力します。
DMX 信号を出力し続けるには、定期的に DrMX_Write() を繰り返し使用します。
前回の DrMX_Write() による出力が完了していない場合、タイムアウト値まで待ちます。
出力を開始すると DrMX_Write() は終了し 1 を返します。
タイムアウトなどで出力を開始できない場合は 0 を返します。
タイムアウト以外にも、実行スレッドが未処理のメッセージを持っている場合など、出力を開始せずに 0 を返します。
タイムアウトの時間精度は実行するコンピューター環境により異なりますので目安程度として下さい。

DWORD WINAPI DrMX_Read(RDrMX aR, BYTE* aP, DWORD aL, DWORD aT);
DMX からのデータを読み込みます。
前回の DrMX_Read() による読み込みが完了していない場合、タイムアウト値まで待ちます。
読み込みデータがある場合は DrMX_Read() は終了し、読み込まれたバイト数を返します。
aL で指定されたよりも多いデータは捨てられます。
タイムアウトなどで読み込みデータがない場合は 0 を返します。
タイムアウト以外にも、実行スレッドが未処理のメッセージを持っている場合など、読み込むことなく 0 を返します。
タイムアウトの時間精度は実行するコンピュータ環境により異なりますので目安程度として下さい。

RDrMX WINAPI DrMX_OpenID(LPCTSTR aID);
特定のインターフェースハードウェアの使用を始めます。
利用できる場合、インターフェースハードウェアへのポインター(参照)を返します。
ハードウェアが接続されていないなど、何らかの理由で利用できない場合は NULL を返します。

BOOL WINAPI DrMX_SetTiming(RDrMX aR, DWORD aBrk, DWORD aMAB, DWORD aMBS);
出力信号のタイミングを設定します。
ハードウェアが接続されていないなど、何らかの理由で設定できない場合は FALSE を返します。


使用例

   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)