HidP_GetUsageValue函式（hidpi.h）

發行項
02/07/2025

HidP_GetUsageValue 例程會擷取與 HID 控件值相關聯的數據，該值符合 HID 報表中的選取準則。

語法

NTSTATUS HidP_GetUsageValue(
  [in]  HIDP_REPORT_TYPE     ReportType,
  [in]  USAGE                UsagePage,
  [in]  USHORT               LinkCollection,
  [in]  USAGE                Usage,
  [out] PULONG               UsageValue,
  [in]  PHIDP_PREPARSED_DATA PreparsedData,
  [in]  PCHAR                Report,
  [in]  ULONG                ReportLength
);

參數

[in] ReportType

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

[in] UsagePage

指定值使用頁面。

[in] LinkCollection

指定包含值的連結集合。如果 LinkCollection 為非零，則例程只會搜尋此連結集合中的使用量;否則，如果 LinkCollection 為零，則例程會搜尋與 PreparsedData相關聯的最上層集合使用量。

[in] Usage

指定值的用法。

[out] UsageValue

例程傳回值數據的緩衝區指標。

[in] PreparsedData

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

[in] Report

包含值的報表指標。

[in] ReportLength

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

傳回值

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

傳回碼	描述
HIDP_STATUS_SUCCESS	例程已成功傳回值數據。
HIDP_INVALID_REPORT_LENGTH	報表長度無效。
HIDP_INVALID_REPORT_TYPE	指定的報表類型無效。
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	集合包含指定類型之報表中指定使用量頁面上的值，但在指定的報表中沒有這類用法。
HIDP_STATUS_INVALID_PREPARSED_DATA	預先剖析的數據無效。
HIDP_STATUS_USAGE_NOT_FOUND	集合不包含指定之報表類型之任何報表中指定使用量頁面上的值。

言論

HidP_GetUsageValue 不會簽署或調整值。若要擷取帶正負號的值，請使用 HidP_GetScaledUsageValue。若要手動指派符號位，可以從值 HIDP_VALUE_CAPS 結構中的資訊判斷符號位的位置。

HidP_GetUsageValue 的設計目的是擷取報表計數為1之使用量的使用量值。如果指定的使用量具有大於 1 的報表計數，則使用量是使用值陣列的一部分，。 HidP_GetUsageValue 只會傳回使用值陣列中的第一個數據項。若要擷取使用值陣列中的所有資料項，請使用 HidP_GetUsageValueArray。

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

要求

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