WdfDeviceAllocAndQueryProperty 函数 (wdfdevice.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfDeviceAllocAndQueryProperty 方法分配缓冲区并检索指定的设备属性。

语法

NTSTATUS WdfDeviceAllocAndQueryProperty(
  [in]           WDFDEVICE                Device,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

参数

[in] Device

框架设备对象的句柄。

[in] DeviceProperty

标识要检索的设备属性的 DEVICE_REGISTRY_PROPERTY类型枚举器。

[in] PoolType

一个POOL_TYPE类型的枚举器，指定要分配的内存类型。

[in, optional] PropertyMemoryAttributes

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

[out] PropertyMemory

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

返回值

如果操作成功， WdfDeviceAllocAndQueryProperty 将返回STATUS_SUCCESS。 其他返回值包括：

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

该方法可能会返回其他 NTSTATUS 值。

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

注解

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

或者，可以使用 WdfDeviceAllocAndQueryPropertyEx 访问通过统一属性模型公开的设备属性。

示例

下面的代码示例使用框架将为请求的属性创建的框架内存对象的属性初始化 WDF_OBJECT_ATTRIBUTES 结构。 然后，该示例调用 WdfDeviceAllocAndQueryProperty 以获取 DevicePropertyPhysicalDeviceObjectName 属性。 WdfDeviceAllocAndQueryProperty 返回后，驱动程序可以调用 WdfMemoryGetBuffer 以获取指向包含名称字符串的缓冲区的指针。

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFDEVICE  device;
WDFMEMORY  memory;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = device;

status = WdfDeviceAllocAndQueryProperty(device,
                                        DevicePropertyPhysicalDeviceObjectName,
                                        NonPagedPool,
                                        &attributes,
                                        &memory
                                        );
if (!NT_SUCCESS(status)) {
    return STATUS_UNSUCCESSFUL;
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfdevice.h (包括 Wdf.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

WdfDeviceQueryProperty