ボタン機能配列

  • [アーティクル]

ボタン機能配列には、特定の種類の HID レポートの最上位のコレクションでサポートされているボタンの使用法に関する情報が含まれています。 コレクションの機能に関する情報は、その HIDP_CAPS 構造体に含まれています。

ユーザー モード アプリケーションまたはカーネル モード ドライバーは、次の HIDClass サポート ルーチンのいずれかを使用して、ボタンの機能情報を取得します。

  • HidP_GetButtonCaps は、指定したレポートの種類に含まれるすべてのボタン使用法を説明するボタン機能配列を返します。

  • HidP_GetSpecificButtonCaps は、呼び出し元が指定した使用法ページ、使用法 ID、およびリンク コレクションによって返されるボタン機能情報をフィルター処理します。

ボタン機能配列には HIDP_BUTTON_CAPS 構造体が含まれており、それぞれに HID 使用法または使用法範囲に関する次の情報が含まれています。

  • 使用法または使用法範囲を示す使用法ページ

  • ボタン データを含むレポートのレポート ID

  • 使用法 ID または使用法範囲

  • 使用法がエイリアス化された使用法であるかどうかを示すフラグ

  • 使用法または使用法範囲を含むリンク コレクション

  • 使用法または使用法範囲に関連付けられている文字列記述子と指定子 (Designator Index 項目と String Index 項目を参照)

  • HID パーサーが使用法または使用法範囲に割り当てたデータ インデックス

一般に、次の条件は、ボタン機能配列によって記述されたすべての使用法に対して保持されます。

  • 各機能構造は、変数メイン項目または配列メイン項目に関連付けられている単一の使用法または使用法範囲を表します。

  • エイリアス化された使用法は、変数メイン項目と共に使用できます。 配列項目に関連付けられている使用法はエイリアス化できません。 使用法範囲はエイリアス化できません。

  • HID パーサーは、各ボタンに使用法を割り当てるために必要な最小限の数の使用法のみを使用します。 パーサーは、レポート記述子で指定された順序で使用法を割り当てます。 レポート記述子内の不要な使用法は破棄されます。 ボタン機能配列には、破棄された使用法に関する情報は含まれません。

  • 変数項目に指定された使用法の数が項目内のボタンの数より少ない場合、機能配列には、1 つのボタン使用法 (変数メイン項目のレポート記述子で指定された最後の使用法) を記述する機能構造が 1 つだけ含まれます。 ただし、レポート数が 1 より大きい使用法値については、「使用法値配列」を参照してください。

  • HID パーサーは、機能配列で説明されている各使用法に一意のデータ インデックスを割り当てます。

次のトピックでは、ボタン機能配列で機能構造を編成および設定する方法について説明します。

変数メイン項目のボタン使用法

レポート記述子で指定された各使用法または使用法範囲は、ボタン機能配列内の独自の機能構造によって記述されます。

機能構造の IsAlias メンバーは、次のように n 個のエイリアス化された使用法のセットを指定するために使用されます。

  • IsAlias は、機能配列に追加された最初の n-1 機能構造体で TRUE に設定されます。 IsAlias は、n 番目の機能構造で FALSE に設定されます。 推奨される使用法は、シーケンス内の最後のエイリアス化された使用法です。

アプリケーションまたはドライバーは、そのようなシーケンスをスキャンすることで、エイリアス化されるボタンの使用法を決定できます。

次の表は、エイリアス化された 3 つの使用法の例をまとめたものです。

レポート記述子のエイリアス化された使用法の順序 機能配列の使用法の順序 IsAlias メンバー値
使用法 1 使用法 3 TRUE
使用法 2 使用法 2 TRUE
使用法 3 使用法 1 FALSE

使用法とデータ インデックスの相互参照方法については、「データ インデックス」を参照してください。

配列メイン項目のボタン使用法

レポート記述子で指定されたボタン配列メイン項目の各使用法または使用法範囲は、ボタン機能配列内の独自の機能構造によって記述されます。 機能構造が機能配列に追加される順序は、メイン項目の使用法が指定された順序の逆になります。

HID パーサーは、レポート記述子で使用法が指定されている順序で、データ インデックスを配列項目に関連付けられている各使用法に割り当てます。 たとえば、次の表は、レポート記述子で指定されている一連の使用法と、機能配列で指定されている使用法とデータ インデックスの対応関係を示しています。 (この表では、n は、パーサーが配列項目に関連付けられている最初の使用法に割り当てる最初のデータ インデックスです)。

レポート記述子での使用法の順序 機能配列での使用法の順序 DataIndex または DataIndexMin ～ DataIndexMax
使用法 1 使用法範囲 2 n+7 ～ n+8
使用法範囲 1 (4 つの使用法) 使用法 2 n+5
使用法 2 使用法範囲 1 n+1 ～ n+4
使用法範囲 2 (2 つの使用法) 使用法 1 n