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，但存在於不同的集合中。 如果 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 | PreparsedData 參數無效 |
| HIDP_STATUS_INVALID_REPORT_LENGTH | 報表封包的長度不等於 指定之 ReportType HIDP_CAPS 結構中指定的長度 |
| HIDP_STATUS_NOT_BUTTON_ARRAY | 指定的控制項不是按鈕數位 |
| HIDP_STATUS_BUFFER_TOO_SMALL | 傳入緩衝區的大小，用來傳回數位大小太小 |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | 指定的使用方式頁面、使用方式和連結集合存在於報表中，其報表標識符與傳入的報表不同 |
| HIDP_STATUS_USAGE_NOT_FOUND | 此 ReportType 的任何報表中都沒有使用方式頁面、使用方式和連結集合組合 |
言論
呼叫端應該使用 HidP_GetVersion 來判斷此函式是否可用。 HidP_GetButtonArray 只有在 HidP_GetVersion 傳回兩個或更新的值時，才能使用。 第二版的 API 對應至 Windows 11。
當描述主要專案之使用順序中的最後一個使用方式時，必須重複按鈕陣列，因為定義的使用量比針對指定的主要專案宣告的 ReportCount 少。 在此情況下，會針對該使用量配置單一 HIDP_BUTTON_CAPS，並將 HIDP_BUTTON_CAPS 的 ReportCount 設定為反映使用量所參考的欄位數目。
描述按鈕陣列的 HIDP_BUTTON_CAPS 一律 ReportCount 大於一個。 如果 ReportCount 等於一個，則它不是按鈕數位，而且不能與 HidP_GetButtonArray搭配使用。 請改為參閱 HidP_GetUsages。
要求
| 要求 | 價值 |
|---|---|
| 標頭 | hidpi.h |