HidP_SetButtonArray関数 (hidpi.h)
HidP_SetButtonArray関数は、HIDP_BUTTON_ARRAY_DATA構造体の配列を介してボタンの状態を設定します。
構文
NTSTATUS HidP_SetButtonArray(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE Usage,
PHIDP_BUTTON_ARRAY_DATA ButtonData,
USHORT ButtonDataLength,
PHIDP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
パラメーター
ReportType
HIDP_REPORT_TYPE列挙型からHidP_OutputまたはHidP_Featureのいずれかの値。
UsagePage
特定の使用状況が参照する使用状況ページ。
LinkCollection
(省略可能)この値を使用すると、 UsagePage と Usage が同じである可能性がありますが、異なるコレクションに存在する 2 つのフィールドを区別できます。 値がHIDP_LINK_COLLECTION_UNSPECIFIEDの場合は、場所に関係なく 、UsagePage と Usage に一致する最初に見つかったボタン配列が返されます。 値がHIDP_LINK_COLLECTION_ROOT場合は、ルート コレクション内の最初に見つかったボタン配列が UsagePage と Usage に一致する値が返されます。
Usage
ボタン配列 HidP_SetButtonArray が設定される使用法。
ButtonData
ボタン配列に設定する値を含むバッファー。
ButtonDataLength
ButtonData バッファー内の要素の数。
PreparsedData
HIDCLASS から返された解析済みデータ。
Report
レポート パケット。 最初のバイトは ReportId である必要があります。
ReportLength
指定されたレポート パケットの長さ (バイト単位)。
戻り値
HidP_SetButtonArray は、次のいずれかの状態値を返します。
| リターン コード | 説明 |
|---|---|
| HIDP_STATUS_SUCCESS | レポート パケット内のボタン配列が正常に設定されました |
| HIDP_STATUS_INVALID_REPORT_TYPE | ReportType が無効です |
| HIDP_STATUS_INVALID_PREPARSED_DATA | PreparsedData が無効です |
| HIDP_STATUS_INVALID_REPORT_LENGTH | レポート パケットの長さが、指定された ReportType のHIDP_CAPS構造体で指定された長さと等しくない |
| HIDP_STATUS_REPORT_DOES_NOT_EXIST | 指定された ReportType に関するレポートがこのデバイスにありません |
| HIDP_STATUS_NOT_BUTTON_ARRAY | 指定されたコントロールがボタン配列ではありません |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | 指定された使用状況ページ、使用状況、およびリンク コレクションが、渡されるレポートとは異なるレポート ID を持つレポートに存在します |
| HIDP_STATUS_USAGE_NOT_FOUND | 使用状況ページ、使用状況、およびリンク コレクションの組み合わせは、この ReportType のレポートに存在しません |
| HIDP_STATUS_DATA_INDEX_OUT_OF_RANGE | 指定されたHIDP_BUTTON_ARRAY_DATA構造体の 1 つの ArrayIndex がこのボタン配列の有効な範囲外である |
注釈
HidP_SetButtonArray は、指定した LinkCollection 内で見つかった最初のボタン配列のボタンの状態を、指定されたレポートに 対して指定された Usage と 共に設定 します。
呼び出し元は 、HidP_GetVersion を使用して、この関数が使用可能かどうかを判断する必要があります。 HidP_SetButtonArray は、 HidP_GetVersion が 2 つ以上の値を返す場合にのみ使用できます。 バージョン 2 の API は、Windows 11に対応しています。
ボタン配列は、指定されたメイン項目に対して宣言された ReportCount よりも使用量が少ないため、メイン項目を記述する一連の使用法の最後の使用法を繰り返す必要がある場合に発生します。 この場合、その使用に対して 1 つのHIDP_BUTTON_CAPSが割り当てられ、使用状況が参照するフィールドの数を反映するようにHIDP_BUTTON_CAPSの ReportCount が設定されます。
ボタン配列を記述する HIDP_BUTTON_CAPS では、常に ReportCount が 1 より大きくなります。 ReportCount が 1 と等しい場合は、ボタン配列ではなく、HidP_SetButtonArrayで使用することはできません。 詳細については、「 HidP_SetUsages」を参照してください。
要件
| 要件 | 値 |
|---|---|
| Header | hidpi.h |