HID レポートを解釈する
この記事では、ユーザーモード アプリケーションとカーネルモード ドライバーが HidP_XxxHIDClass サポート ルーチンを使用して HID レポート内のコントロール データを解釈する方法について説明します。
使用法を指定して値データを抽出する
アプリケーションまたはドライバーは、次のいずれかの HID サポート ルーチンを使用して、HID レポートから値データを抽出できます。
- HidP_GetScaledUsageValue: 符号付きのスケーリングされた値を返します。
- HidP_GetUsageValue: 符号なし形式の非スケーリング値、またはその通常の範囲外のスケーリングされた値を返します。
- HidP_GetUsageValueArray: 使用法の値の配列を返します。
HidP_GetUsageValueArray を使用するには、アプリケーションとドライバーで、使用法の値の配列を保持するのに十分な大きさのゼロ初期化バッファーを割り当てる必要があります。 必要なサイズ (バイト単位) は、使用法の値の配列の HIDP_VALUE_CAPS 構造体の BitSize メンバーと ReportCount メンバーの積であり、最も近いバイトに切り上げられます。
ON に設定されているボタン使用法の抽出
ON (1) に設定されているボタンの HID 使用法を抽出するには、アプリケーションとドライバーで、次の HID サポート ルーチンのいずれかを呼び出します。
- HidP_GetButtons (または HidP_GetUsages): 指定した使用法ページのすべてのボタンの中で、ON に設定されているボタンの使用法 ID を返します。
- HidP_GetButtonsEx (または HidP_GetUsagesEx): ON に設定されているすべてのボタンの使用法ページと使用法 ID を返します。
これらのルーチンは、現在 ON に設定されているすべてのボタンのすべての使用法に関する情報の配列を返します。 暗黙的に、これらのルーチンによって使用法が返されないボタンは、OFF (ゼロ) に設定されています。
これらのルーチンを呼び出すには、まずアプリケーションとドライバーで、ボタンの使用法の配列を返すために使用するバッファーを割り当て、ゼロ初期化する必要があります。 アプリケーションまたはドライバーは、HidP_MaxUsageListLength を呼び出して、レポート内の指定した使用法ページ内のボタンの使用法の数を特定します。 アプリケーションまたはドライバーで 0 の使用法ページを指定した場合、レポート内のすべてのボタンの使用法の数が返されます。
必要なバッファー サイズ (バイト単位) は次のとおりです。
- (HidP_GetButtons の場合) HidP_MaxUsageListLength から返された値に sizeof(USAGE) を掛けた値
- (HidP_GetButtonsEx の場合) HidP_MaxUsageListLength から返された値に sizeof(USAGE_AND_PAGE) を掛けた値
アプリケーションまたはドライバーは、これらのルーチンを使用して、現在 ON に設定されているボタンに関する情報を取得すると、次の HIDClass サポート ルーチンのいずれかを呼び出すことによって、ボタンの現在の状態と以前の状態の違いを特定できるようになります。 これらのルーチンは、使用法に関する情報の 2 つの配列の違いを返します。
データ インデックスによるコントロール データの抽出と設定
データ インデックスを使用して HID レポート内のコントロール データを抽出および設定する場合、アプリケーションまたはドライバーは、次の HIDClass サポート ルーチンを使用できます。
これらのルーチンは、「付加価値」サービスを提供するアプリケーションまたはドライバーで役立ちます。 たとえば、HIDClass デバイスでサポートされているすべてのコントロールにカスタム インターフェイスを提供するものなどです。 その例としては、Microsoft DirectInput が挙げられます。
これらのルーチンを呼び出すアプリケーションまたはドライバーは、レポート内のすべての値を最も効率的に取得および設定できます。 たとえば、HID の使用法別にすべての値データを取得するには、使用法ごとに HidP_GetUsageValue を呼び出す必要があります。 ただし、データ インデックスを基準としてすべての値データを取得する場合は、HidP_GetData を 1 回呼び出すだけでかまいません。
アプリケーションまたはドライバーは、コレクションのボタン機能配列と値機能配列で指定されたデータ インデックスを使用して、HID の使用法を識別します。
使用法を指定して値データを設定する
アプリケーションまたはドライバーは、次のいずれかの HID サポート ルーチンを呼び出すことによって、適切に初期化された HID レポートの値を設定できます。
- HidP_SetScaledUsageValue: レポート内の符号付き値とスケーリングされた値を設定します。
- HidP_SetUsageValue: レポート内の値を設定します。
- HidP_SetUsageValueArray: レポート内の使用法の値の配列を設定します。
使用法を指定してボタンの状態を設定する
アプリケーションまたはドライバーは、次のいずれかの HIDClass サポート ルーチンを呼び出すことによって、適切に初期化された HID レポートのボタンの状態を設定できます。
- HidP_SetButtons (または HidP_SetUsages): 指定したボタンのセットを ON (1) に設定します。
- HidP_UnsetButtons (または HidP_UnsetUsages): 指定したボタンのセットを OFF (ゼロ) に設定します。
データ インデックスによる HID コントロール データの抽出と設定
データ インデックスを使用して HID レポート内のコントロール データを抽出および設定する場合、アプリケーションまたはドライバーは、次の HIDClass サポート ルーチンを使用できます。
これらのルーチンは、「付加価値」サービスを提供するアプリケーションまたはドライバーで役立ちます。 たとえば、HIDClass デバイスでサポートされているすべてのコントロールにカスタム インターフェイスを提供するものなどです。 その例としては、Microsoft DirectInput が挙げられます。
これらのルーチンを呼び出すアプリケーションまたはドライバーは、レポート内のすべての値を最も効率的に取得および設定できます。 たとえば、HID の使用法別にすべての値データを取得するには、使用法ごとに HidP_GetUsageValue を呼び出す必要があります。 ただし、データ インデックスを基準としてすべての値データを取得する場合は、HidP_GetData を 1 回呼び出すだけでかまいません。
アプリケーションまたはドライバーは、コレクションのボタン機能配列と値機能配列で指定されたデータ インデックスを使用して、HID の使用法を識別します。