HidP_GetUsagesEx函式 (hidpi.h)

發行項
03/01/2024

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

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

傳回值

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

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

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

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

規格需求

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