WdfFdoInitAllocAndQueryProperty function (wdffdo.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

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

Syntax

NTSTATUS WdfFdoInitAllocAndQueryProperty(
  [in]           PWDFDEVICE_INIT          DeviceInit,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

Parameters

[in] DeviceInit

A pointer to a WDFDEVICE_INIT structure that the driver obtained from its EvtDriverDeviceAdd callback function.

[in] DeviceProperty

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

[in] PoolType

A POOL_TYPE-typed enumerator value 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 WdfFdoInitAllocAndQueryProperty 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, the method 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 WDFDEVICE_INIT structure was not obtained from driver's EvtDriverDeviceAdd callback function.

The method might also return other NTSTATUS values.

Remarks

The driver must call WdfFdoInitAllocAndQueryProperty before calling WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.

After calling WdfDeviceCreate, a driver can obtain device property information by calling WdfDeviceAllocAndQueryProperty.

For more information about the WdfFdoInitAllocAndQueryProperty method, see Creating Device Objects in a Function Driver.

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

Examples

The following code example calls WdfFdoInitAllocAndQueryProperty to obtain a handle to a framework memory object that contains the name of a device's setup class. Then, the example calls WdfMemoryGetBuffer to obtain a pointer to the buffer that contains the setup class name's Unicode string.

NTSTATUS  status = STATUS_SUCCESS;
PVOID  pMemoryBuffer = NULL;
WDFMEMORY  memory = NULL;

status = WdfFdoInitAllocAndQueryProperty(
                                         DeviceInit,
                                         DevicePropertyClassName, 
                                         NonPagedPool,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &memory
                                         );
if(NT_SUCCESS(status)){
 pMemoryBuffer = WdfMemoryGetBuffer(
                                    memory,
                                    NULL
                                    );
}

Requirements

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