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

HIDP_BUTTON_ARRAY_DATA 結構的陣列，其中將放置按鈕ON的數據。 所需的元素數目是這個控件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 傳回下列其中一個狀態值：

傳回碼 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_NOT_BUTTON_ARRAY 指定的控制項不是按鈕數位
HIDP_STATUS_BUFFER_TOO_SMALL 傳入緩衝區的大小，其中傳回數位大小太小
HIDP_STATUS_INCOMPATIBLE_REPORT_ID 指定的使用方式頁面、使用量和連結集合存在於報表中，其報表標識碼與傳入的報表不同
HIDP_STATUS_USAGE_NOT_FOUND 此 ReportType 的任何報表中都不存在使用方式頁面、使用量和連結集合組合

備註

呼叫端應該使用 HidP_GetVersion 來判斷此函式是否可用。 只有在HidP_GetVersion傳回兩個或更新的值時，才能使用HidP_GetButtonArray。 第二版的 API 會對應至 Windows 11。

當描述主要專案的使用量序列中最後一次使用時，必須重複執行按鈕陣列，因為定義使用量比針對指定的主要專案宣告的 ReportCount 少。 在此情況下，系統會為該使用量配置單一HIDP_BUTTON_CAPS，而HIDP_BUTTON_CAPS的 ReportCount 會設定為反映使用量所參考的欄位數目。

描述按鈕陣列 的HIDP_BUTTON_CAPS 一律會有大於一的 ReportCount 。 如果 ReportCount 等於一個，則它不是按鈕數位，而且不能與 HidP_GetButtonArray搭配使用。 請改為參閱 HidP_GetUsages 。

規格需求

需求 值
標頭 hidpi.h

另請參閱