この記事では、ユーザーモード アプリケーションとカーネルモード ドライバーが 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 は、指定された使用法ページ上のすべてのボタンのうち、オンになっているものの使用法 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 サポート ルーチンを呼び出すことによって、適切に初期化された HID レポートの値を設定できます。
- HidP_SetScaledUsageValue: レポート内で符号付きスケーリング値を設定します。
- HidP_SetUsageValue: レポート内の値を設定します。
- HidP_SetUsageValueArray: レポート内の使用値の配列を設定します。
使用法を指定してボタンの状態を設定する
アプリケーションまたはドライバーは、次のいずれかの HIDClass サポート ルーチンを呼び出すことで、初期化済みの適切なHIDレポートのボタンの状態を設定できます。
- HidP_SetButtons (または HidP_SetUsages): 特定のボタンセットを ON (1) に設定します。
- HidP_UnsetButtons (または HidP_UnsetUsages): 指定したボタンのセットをOFFに設定します。
データ インデックスによるコントロール データの抽出と設定
データ インデックスを使用して HID レポート内のコントロールデータを抽出および設定する場合、アプリケーションまたはドライバーは、次の HIDClass サポートルーチンを使用できます：
- HidP_GetData
- HidP_SetData
これらのルーチンは、「付加価値」サービスを提供するアプリケーションまたはドライバーで役立ちます。 たとえば、HIDClass デバイスでサポートされているすべてのコントロールにカスタム インターフェイスを提供するものなどです。 Microsoft DirectInput が 1 つの例です。
これらのルーチンを呼び出すアプリケーションまたはドライバーは、レポート内のすべての値を最も効率的に取得および設定できます。 たとえば、 HID 使用法ですべての値データを取得するには、使用状況ごとに HidP_GetUsageValue を呼び出す必要があります。 ただし、データ インデックスを基準としてすべての値データを取得する場合は、HidP_GetData を 1 回呼び出すだけでかまいません。
アプリケーションまたはドライバーは、コレクションのボタン機能配列と値機能配列で指定されたデータ インデックスを使用して、HID の使用法を識別します。
関連項目
- HID レポートの初期化