HidP_GetUsages函式（hidpi.h）

發行項
02/07/2025

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 所指定之所有按鈕的使用方式，UsagePage。

[in, out] UsageLength

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

[in] PreparsedData

最上層集合預先剖析資料的指標。

[out] Report

報表的指標。

[in] ReportLength

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

傳回值

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

傳回碼	描述
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。
目標平臺	普遍
標頭	hidpi.h （包括 Hidpi.h）
連結庫	Hidparse.lib
IRQL	<= DISPATCH_LEVEL