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 ，但存在於不同的集合中。 如果值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 傳回下列其中一個狀態值：
| 傳回碼 | Description |
|---|---|
| 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 | 指定的使用方式頁面、使用量和連結集合存在於報表中，其報表標識碼與傳入的報表不同 |
| HIDP_STATUS_USAGE_NOT_FOUND | 此 ReportType 的任何報表中都不存在使用方式頁面、使用量和連結集合組合 |
| HIDP_STATUS_DATA_INDEX_OUT_OF_RANGE | 其中一個提供的HIDP_BUTTON_ARRAY_DATA結構的 ArrayIndex 超出此按鈕陣列的有效範圍 |
備註
HidP_SetButtonArray設定指定之 LinkCollection 內所找到第一個按鈕陣列的按鈕狀態，並提供指定之報表的使用量。
呼叫端應該使用 HidP_GetVersion 來判斷此函式是否可用。 只有在HidP_GetVersion 傳回兩個或更新的值時， 才能使用HidP_SetButtonArray 。 第二版的 API 會對應至 Windows 11。
當描述主要專案的使用量序列中最後一次使用時，必須重複執行按鈕陣列，因為定義使用量比針對指定的主要專案宣告的 ReportCount 少。 在此情況下，系統會為該使用量配置單一HIDP_BUTTON_CAPS，而HIDP_BUTTON_CAPS的 ReportCount 會設定為反映使用量所參考的欄位數目。
描述按鈕陣列 的HIDP_BUTTON_CAPS ，一律會有一個大於一的 ReportCount 。 如果 ReportCount 等於一個，則它不是按鈕數位，而且無法與 HidP_SetButtonArray搭配使用。 如需詳細資訊，請參閱 HidP_SetUsages。
規格需求
| 需求 | 值 |
|---|---|
| 標頭 | hidpi.h |