WdfIoTargetAllocAndQueryTargetProperty 函数（wdfiotarget.h）

项目
03/22/2025

[仅适用于 KMDF]

WdfIoTargetAllocAndQueryTargetProperty 方法分配缓冲区并检索指定 I/O 目标的指定设备属性。

语法

NTSTATUS WdfIoTargetAllocAndQueryTargetProperty(
  [in]           WDFIOTARGET              IoTarget,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

参数

[in] IoTarget

从先前调用 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 或从专用 I/O 目标提供的方法获取的本地或远程 I/O 目标对象的句柄。

[in] DeviceProperty

一个 DEVICE_REGISTRY_PROPERTY类型的值，用于标识要检索的设备属性。

[in] PoolType

指定要分配的内存类型的 POOL_TYPE类型值。

[in, optional] PropertyMemoryAttributes

指向调用方分配 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构描述函数将分配的内存对象的对象属性。此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[out] PropertyMemory

指向 WDFMEMORY 类型位置的指针，该位置接收框架内存对象的句柄。

返回值

如果作成功，则 WdfIoTargetAllocAndQueryTargetProperty 返回STATUS_SUCCESS。否则，此方法可能会返回以下值之一：

返回代码	说明
STATUS_INVALID_PARAMETER 或STATUS_INVALID_PARAMETER_2	指定的 DeviceProperty 参数的值无效。
STATUS_INVALID_DEVICE_REQUEST	设备的驱动程序尚未报告设备的属性。

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

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

注解

WdfIoTargetAllocAndQueryTargetProperty 方法确定保存所请求的设备属性所需的内存量。此方法分配足够的内存来保存数据，并向描述已分配内存的框架内存对象返回句柄。若要访问数据，驱动程序可以调用 WdfMemoryGetBuffer。

有关 WdfIoTargetAllocAndQueryTargetProperty的详细信息，请参阅获取有关常规 I/O 目标的信息。

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

例子

下面的代码示例调用 WdfIoTargetAllocAndQueryTargetPropertyproperty 以获取 DevicePropertyFriendlyName 属性。 WdfIoTargetAllocAndQueryTargetProperty 返回后，驱动程序可以调用 WdfMemoryGetBuffer 以获取指向包含名称字符串的缓冲区的指针。

WDFMEMORY  targetName;
NTSTATUS  status;

status = WdfIoTargetAllocAndQueryTargetProperty(
                                                Target,
                                                DevicePropertyFriendlyName,
                                                NonPagedPool,
                                                WDF_NO_OBJECT_ATTRIBUTES,
                                                &targetName
                                                );

要求

要求	价值
目标平台	普遍
最低 KMDF 版本	1.0
标头	wdfiotarget.h （包括 Wdf.h）
图书馆	Wdf01000.sys（请参阅框架库版本控制。
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）