WdfIoTargetQueryTargetProperty 函式 (wdfiotarget.h)

發行項
02/29/2024

[僅適用於 KMDF]

WdfIoTargetQueryTargetProperty 方法會擷取指定 I/O 目標的指定裝置屬性。

語法

NTSTATUS WdfIoTargetQueryTargetProperty(
  [in]            WDFIOTARGET              IoTarget,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

參數

[in] IoTarget

從先前呼叫 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 取得的本機或遠端 I/O 目標物件的句柄，或從特製化 I/O 目標所提供的方法取得。

[in] DeviceProperty

識別要擷取之裝置屬性的DEVICE_REGISTRY_PROPERTY型別值。

[in] BufferLength

PropertyBuffer 指向之緩衝區的大小，以位元組為單位。

[out, optional] PropertyBuffer

呼叫端配置的緩衝區指標，可接收要求的裝置屬性資訊。如果 BufferLength 為零，這個指標可以是 NULL。

[out] ResultLength

傳回位置的指標包含 WdfIoTargetQueryTargetProperty 儲存在 PropertyBuffer 所指向之緩衝區中之資訊的大小，以位元組為單位。如果 WdfIoTargetQueryTargetProperty 傳回STATUS_BUFFER_TOO_SMALL，此位置會收到所需的緩衝區大小。

傳回值

如果作業成功，WdfIoTargetQueryTargetProperty 會傳回STATUS_SUCCESS。否則，此方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_BUFFER_TOO_SMALL	PropertyBuffer 參數指向的緩衝區太小，無法接收要求的資訊。
STATUS_INVALID_PARAMETER_2	指定 DeviceProperty 參數的值無效。
STATUS_INVALID_DEVICE_REQUEST	裝置的驅動程式尚未回報裝置的屬性。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

在驅動程式收到裝置屬性數據之前，它們通常會呼叫 WdfIoTargetQueryTargetProperty 方法來取得所需的緩衝區大小。對於某些屬性，當傳回所需的大小，以及驅動程式再次呼叫 WdfIoTargetQueryTargetProperty 時，數據大小可能會變更。因此，驅動程式應該在迴圈內呼叫 WdfIoTargetQueryTargetProperty ，直到傳回狀態未STATUS_BUFFER_TOO_SMALL為止。

您的驅動程式可以呼叫 WdfIoTargetAllocAndQueryTargetProperty，而不是呼叫 WdfIoTargetQueryTargetProperty，這會配置緩衝區並將屬性資訊放在緩衝區中。

如需 WdfIoTargetQueryTargetProperty 的詳細資訊，請參閱取得一般 I/O 目標的相關信息。

如需 I/O 目標的詳細資訊，請參閱使用 I/O 目標。

範例

下列程式代碼範例會取得裝置的 DevicePropertyUINumber 屬性。此範例會呼叫 WdfIoTargetQueryTargetProperty ，而不是 WdfIoTargetAllocAndQueryTargetProperty ，因為已知 UI 編號的長度。

ULONG targetUINumber, resultLength;
NTSTATUS status;

status = WdfIoTargetQueryTargetProperty(
                                        target,
                                        DevicePropertyUINumber,
                                        sizeof(targetNumber),
                                        &targetUINumber,
                                        &resultLength
                                        );

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
標頭	wdfiotarget.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)