HidP_GetButtonArray関数 (hidpi.h)
HidP_GetButtonArray は、指定したレポートの HIDP_BUTTON_ARRAY_DATA 構造体の配列を返します。
構文
NTSTATUS HidP_GetButtonArray(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE Usage,
PHIDP_BUTTON_ARRAY_DATA ButtonData,
PUSHORT ButtonDataLength,
PHIDP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
パラメーター
ReportType
HIDP_REPORT_TYPE 列挙型の値。
UsagePage
特定の使用状況が参照する使用状況ページ。
LinkCollection
(省略可能)この値を使用すると、UsagePage と Usage が異なるコレクションに存在する可能性がある 2 つのフィールドを区別できます。 LinkCollection の値が HIDP_LINK_COLLECTION_UNSPECIFIEDされている場合は、場所に関係なく、UsagePage と Usage に一致する最初のボタン配列が返されます。 LinkCollection 値が HIDP_LINK_COLLECTION_ROOTされている場合は、ルート コレクション内にある最初のボタン配列が、UsagePage と一致する Usage が返されます。
Usage
ボタン HidP_GetButtonArray 取得する使用状況。
ButtonData
ON に設定されたボタンのデータが配置される HIDP_BUTTON_ARRAY_DATA 構造体の配列。 必要な要素の数は、このコントロールの HIDP_BUTTON_CAPS の ReportCount フィールドです。 このバッファーは呼び出し元によって提供されます。
ButtonDataLength
入力として、このパラメーターは、ButtonData パラメーターの長さを、バイト数ではなく配列要素の数で指定します。 出力として、HIDP_STATUS_SUCCESSが返された場合、この値は、関数によって入力された配列要素の数を示すように設定されます。 返される HIDP_BUTTON_ARRAY_DATA 構造体の最大数は、HIDP_BUTTON_CAPSによって決まります。ReportCount。 HIDP_STATUS_BUFFER_TOO_SMALLが返された場合、この値には、要求を正常に完了するために必要な配列要素の数が含まれます。
PreparsedData
HIDCLASSによって返される事前解析済みデータ。
Report
レポート パケット。 最初のバイトは、ReportIdである必要があります。 これは、レポートがシステムから読み取られる場合に正しく設定されます。
ReportLength
指定されたレポート パケットの長さ (バイト単位)。
戻り値
HidP_GetButtonArray は、次のいずれかの状態値を返します。
| リターン コード | 形容 |
|---|---|
| HIDP_STATUS_SUCCESS | レポート パケットからボタンを正常に取得しました |
| HIDP_STATUS_INVALID_REPORT_TYPE | ReportType パラメーターが無効です |
| HIDP_STATUS_INVALID_PREPARSED_DATA | PreparesedData パラメーターが無効です |
| HIDP_STATUS_INVALID_REPORT_LENGTH | レポート パケットの長さが、指定された ReportType の HIDP_CAPS 構造体で指定された長さと等しくない |
| HIDP_STATUS_NOT_BUTTON_ARRAY | 指定されたコントロールがボタン配列ではありません |
| HIDP_STATUS_BUFFER_TOO_SMALL | 配列を返す渡されたバッファーのサイズが小さすぎます |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | 指定された使用状況ページ、使用状況、およびリンク コレクションが、渡されるレポートとは異なるレポート ID を持つレポートに存在します |
| HIDP_STATUS_USAGE_NOT_FOUND | 使用状況ページ、使用状況、およびリンク コレクションの組み合わせは、この ReportType のレポートには存在しません |
備考
呼び出し元は、HidP_GetVersion を使用して、この関数が使用可能かどうかを判断する必要があります。 HidP_GetButtonArray は、HidP_GetVersion が 2 以上の値を返す場合にのみ使用できます。 バージョン 2 の API は Windows 11 に対応しています。
ボタン配列は、メインアイテムを記述する一連の使用法の最後の使用法を繰り返す必要がある場合に発生します。これは、指定されたメインアイテムに対して宣言された ReportCount よりも少ない使用法が定義されているためです。 この場合、その使用状況には 1 つの HIDP_BUTTON_CAPS が割り当てられ、HIDP_BUTTON_CAPS の ReportCount は、使用状況が参照するフィールドの数を反映するように設定されます。
ボタン配列を記述する HIDP_BUTTON_CAPS には、常に ReportCount 1 より大きい が含まれます。 ReportCount 1 と等しい場合は、ボタン配列ではなく、HidP_GetButtonArrayで使用することはできません。 代わりに HidP_GetUsages を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| ヘッダー | hidpi.h |