HidP_GetUsagesEx函式（hidpi.h）

發行項
02/07/2025

HidP_GetUsagesEx 例程會傳回 HID 報表中設定為 ON 的所有 HID 控件按鈕清單，使用方式。

語法

NTSTATUS HidP_GetUsagesEx(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USHORT               LinkCollection,
  [in, out] PUSAGE_AND_PAGE      ButtonList,
  [in, out] ULONG                *UsageLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData,
  [in]      PCHAR                Report,
  [in]      ULONG                ReportLength
);

參數

[in] ReportType

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

[in] LinkCollection

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

[in, out] ButtonList

呼叫端配置的緩衝區指標，例程會使用傳回使用量，並使用量頁面設定為 ON （1）的每個按鈕識別碼。

[in, out] UsageLength

指定 ButtonList 緩衝區的輸入、長度、陣列元素。指定在輸出時，目前在指定報表中設定為 ON 的數位使用量。

[in] PreparsedData

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

[in] Report

包含按鈕數據的報表指標。

[in] ReportLength

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

傳回值

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

傳回碼	描述
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_MaxUsageListLength，以判斷針對指定報表類型傳回的按鈕數目上限。或者，應用程式或驅動程式可以呼叫 HidP_GetUsagesEx，並將 （*UsageLength） 設定為零，以傳回 UsageLength中所需的長度。換句話說，UsageLength 應該是指向 ULONG 值的有效指標，0 以取得所需的長度。

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

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

要求

要求	價值
最低支援的用戶端	適用於 Windows 2000 和更新版本的 Windows。
目標平臺	普遍
標頭	hidpi.h （包括 Hidpi.h）
連結庫	Hidparse.lib
IRQL	<= DISPATCH_LEVEL