wdfIoTargetQueryTargetProperty 函数 (wdfiotarget.h)

[仅适用于 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

从以前调用 WdfDeviceGetIoTargetWdfIoTargetCreate 或从专用 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。 否则,此方法可能会返回以下值之一:

返回代码 说明
STATUS_BUFFER_TOO_SMALL
PropertyBuffer 参数指向的缓冲区太小,无法接收请求的信息。
STATUS_INVALID_PARAMETER_2
指定的 DeviceProperty 参数的值无效。
STATUS_INVALID_DEVICE_REQUEST
设备的驱动程序尚未报告设备的属性。
 

此方法还可以返回其他 NTSTATUS 值

如果驱动程序提供无效的对象句柄,则会发生 bug 检查。

备注

在驱动程序接收设备属性数据之前,它们通常调用 WdfIoTargetQueryTargetProperty 方法以获取所需的缓冲区大小。 对于某些属性,当返回所需大小和驱动程序再次调用 WdfIoTargetQueryTargetProperty 时,数据大小可能会发生更改。 因此,驱动程序应调用 循环中的 WdfIoTargetQueryTargetProperty ,直到返回状态未STATUS_BUFFER_TOO_SMALL为止。

驱动程序可以调用 WdfIoTargetAllocAndQueryTargetProperty,而不是调用 WdfIoTargetTargetProperty,后者分配缓冲区并将属性信息放在缓冲区中。

有关 WdfIoTargetQueryTargetProperty 的详细信息,请参阅 获取有关常规 I/O 目标的信息

有关 I/O 目标的详细信息,请参阅 使用 I/O 目标

示例

下面的代码示例获取设备的 DevicePropertyUINumber 属性。 该示例调用 WdfIoTargetQueryTargetProperty 而不是 WdfIoTargetAllocAndQueryTargetProperty ,因为 UI 编号的长度是已知的。

ULONG targetUINumber, resultLength;
NTSTATUS status;

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

要求

   
目标平台 通用
最低 KMDF 版本 1.0
Header wdfiotarget.h (包括 Wdf.h)
Library Wdf01000.sys (请参阅框架库版本控制.)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf) KmdfIrql (kmdf) KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf)

另请参阅

DEVICE_REGISTRY_PROPERTY

WdfDeviceGetIoTarget

WdfDeviceQueryProperty

WdfIoTargetAllocAndQueryTargetProperty

WdfIoTargetCreate