HidP_GetUsageValueArray函式 (hidpi.h)

發行項
03/05/2024

HidP_GetUsageValueArray例程會從 HID 報表擷取與 HID 控制項使用值數組相關聯的數據。

語法

NTSTATUS HidP_GetUsageValueArray(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [in]      USAGE                Usage,
  [in, out] PCHAR                UsageValue,
  [in]      USHORT               UsageValueByteLength,
  [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

指定使用值陣列的使用方式。

[in, out] UsageValue

呼叫端配置的緩衝區指標，其中例程會傳回與使用值陣列相關聯的數據。

[in] UsageValueByteLength

在 UsageValue指定緩衝區的長度，以位元組為單位。

[in] PreparsedData

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

[in] Report

包含值的報表指標。

[in] ReportLength

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

傳回值

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

傳回碼	Description
HIDP_STATUS_SUCCESS	例程已成功傳回值的數據。
HIDP_INVALID_REPORT_LENGTH	報表長度無效。
HIDP_INVALID_REPORT_TYPE	指定的報表類型無效。
HIDP_STATUS_NOT_VALUE_ARRAY	要求的使用量不是使用值陣列。
HIDP_STATUS_BUFFER_TOO_SMALL	UsageValue 緩衝區太小，無法保存要求的使用量。
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	集合包含指定類型之報表中指定使用量頁面上的使用量值陣列，但在指定的報表中沒有這類用法。
HIDP_STATUS_INVALID_PREPARSED_DATA	預先剖析的數據無效。
HIDP_STATUS_USAGE_NOT_FOUND	集合不包含指定報表類型之任何報表之指定使用量頁面上的使用量值陣列。

備註

UsageValueByteLength 的必要大小，是以位元組為單位，方法是將使用量值陣列HIDP_VALUE_CAPS結構的 BitSize 和 ReportCount 成員相乘，並將結果四捨五入到最接近的位元組。

HidP_GetUsageValueArray 以小到小到小的順序設定 UsageValue 緩衝區，從使用量數據的最小有效位開始。數據不是位元組對齊，而且會移位，使數據最不重要的位位於 UsageValue 緩衝區的第一個位。

HidP_GetUsageValueArray 的設計目的是擷取其報表計數大於 1 之使用量的所有使用量值。若要擷取其報表計數等於1的使用量，請使用 HidP_GetUsageValue。

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

規格需求

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