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,則不論位置為何,都會傳回符合 UsagePageUsage 的第一個找到按鈕陣列。 如果值HIDP_LINK_COLLECTION_ROOT,則會傳回根集合中符合 UsagePageUsage 的第一個找到按鈕陣列。

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 報表封包的長度不等於指定ReportTypeHIDP_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_CAPSReportCount設定為反映使用量所參考的欄位數目。

描述按鈕陣列 的HIDP_BUTTON_CAPS ,一律會有 ReportCount 大於一。 如果 ReportCount 等於一個,則它不是按鈕陣列,無法與 HidP_SetButtonArray搭配使用。 如需詳細資訊,請參閱 HidP_SetUsages

必要條件

   
標頭 hiDPI.h

另請參閱