WdfIoTargetAllocAndQueryTargetProperty 函数 (wdfiotarget.h)

项目
08/08/2023

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

本地或远程 I/O 目标对象的句柄，该对象是从以前调用 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 或从专用 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 目标。

示例

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

WDFMEMORY  targetName;
NTSTATUS  status;

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

要求

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