WdfDeviceAllocAndQueryProperty function (wdfdevice.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfDeviceAllocAndQueryProperty method allocates a buffer and retrieves a specified device property.

Syntax

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

Parameters

[in] Device

A handle to a framework device object.

[in] DeviceProperty

A DEVICE_REGISTRY_PROPERTY-typed enumerator that identifies the device property to be retrieved.

[in] PoolType

A POOL_TYPE-typed enumerator that specifies the type of memory to be allocated.

[in, optional] PropertyMemoryAttributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that describes object attributes for the memory object that the function will allocate. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] PropertyMemory

A pointer to a WDFMEMORY-typed location that receives a handle to a framework memory object.

Return value

If the operation succeeds, WdfDeviceAllocAndQueryProperty returns STATUS_SUCCESS. Additional return values include:

Return code	Description
STATUS_INVALID_PARAMETER or STATUS_INVALID_PARAMETER_2	The specified DeviceProperty value is invalid.
STATUS_INVALID_DEVICE_REQUEST	The device's drivers have not yet reported the device's properties.

The method might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

The WdfDeviceAllocAndQueryProperty method determines the amount of memory that is necessary to hold the requested device property. It allocates enough memory to hold the data, and returns a handle to a framework memory object that describes the allocated memory. To access the data, your driver can call WdfMemoryGetBuffer.

Alternatively, you can use WdfDeviceAllocAndQueryPropertyEx to access device properties that are exposed through the Unified Property Model.

Examples

The following code example initializes a WDF_OBJECT_ATTRIBUTES structure with attributes for the framework memory object that the framework will create for the requested property. Then, the example calls WdfDeviceAllocAndQueryProperty to obtain the DevicePropertyPhysicalDeviceObjectName property. After WdfDeviceAllocAndQueryProperty returns, the driver can call WdfMemoryGetBuffer to obtain a pointer to the buffer that contains the name string.

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;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfdevice.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via