HidP_GetUsages函式 (hidpi.h)

發行項
02/26/2024

HidP_GetUsages例程會傳回指定使用量頁面上的所有 HID 控件按鈕使用方式清單，並且設定為 HID 報表中的 ON。

語法

NTSTATUS HidP_GetUsages(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [out]     PUSAGE               UsageList,
  [in, out] PULONG               UsageLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData,
  [out]     PCHAR                Report,
  [in]      ULONG                ReportLength
);

參數

[in] ReportType

指定可識別報表類型的 HIDP_REPORT_TYPE 列舉值。

[in] UsagePage

指定按鈕使用方式的使用方式頁面。例程只會傳回此使用頁面上按鈕的相關信息。

[in] LinkCollection

指定按鈕使用方式的連結集合。如果 LinkCollection 為非零，例程只會傳回此連結集合包含之按鈕的相關信息;否則，如果LinkCollection為零，例程會傳回與 PreparsedData 相關聯之最上層集合中所有按鈕的相關信息。

[out] UsageList

呼叫端配置的緩衝區指標，此例程會用來傳回所有設定為 ON 且屬於 UsagePage 所指定使用頁面之按鈕的使用方式。

[in, out] UsageLength

指定 UsageList 緩衝區的輸入、長度、陣列元素。在輸出上，指定在指定的使用頁面上設定為 ON 的按鈕數目。

[in] PreparsedData

最上層集合預先分析數據的指標。

[out] Report

報表的指標。

[in] ReportLength

指定位於報表之報表的長度，以位元組為單位。

傳回值

HidP_GetUsages 傳回下列其中一個狀態值：

傳回碼	Description
HIDP_STATUS_SUCCESS	例程已成功傳回設定為 ON 的所有按鈕使用方式。
HIDP_INVALID_REPORT_LENGTH	報表長度無效。
HIDP_INVALID_REPORT_TYPE	指定的報表類型無效。
HIDP_STATUS_BUFFER_TOO_SMALL	UsageList 緩衝區太小，無法保留目前在指定使用量頁面上設定為 ON 的所有使用量。
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	集合包含指定類型之報表中指定使用量頁面上的按鈕，但指定的報表中沒有這類用法。
HIDP_STATUS_INVALID_PREPARSED_DATA	預先分析的數據無效。
HIDP_STATUS_USAGE_NOT_FOUND	集合不包含指定報表類型之任何報表中指定使用方式頁面上的任何按鈕。

備註

使用者模式應用程式和內核模式驅動程式會呼叫 HidP_MaxUsageListLength ，以判斷可針對指定報表類型傳回的按鈕數目上限。或者，應用程式或驅動程式可以呼叫 HidP_GetUsages， 並將 (*UsageLength) 設定為零，以傳回 UsageLength 中所需的長度。換句話說， UsageLength 應該是指向 ULONG 值 0 的有效指標，以取得所需的長度。

應用程式或驅動程式會從最上層集合HIDP_CAPS結構中的XxxReportByteLength 成員判斷所需的報表長度。

如需詳細資訊，請參閱 HID 集合。

規格需求

需求	值
最低支援的用戶端	可在 Windows 2000 和更新版本的 Windows 中使用。
目標平台	Universal
標頭	hidpi.h (包含 Hidpi.h)
程式庫	Hidparse.lib
IRQL	<= DISPATCH_LEVEL