WdfIoTargetAllocAndQueryTargetProperty function (wdfiotarget.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfIoTargetAllocAndQueryTargetProperty method allocates a buffer and retrieves a specified device property for a specified I/O target.

Syntax

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

Parameters

[in] IoTarget

A handle to a local or remote I/O target object that was obtained from a previous call to WdfDeviceGetIoTarget or WdfIoTargetCreate or from a method that a specialized I/O target supplies.

[in] DeviceProperty

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

[in] PoolType

A POOL_TYPE-typed 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 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

WdfIoTargetAllocAndQueryTargetProperty returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

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

This method also might return other NTSTATUS values.

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

Remarks

The WdfIoTargetAllocAndQueryTargetProperty method determines the amount of memory that is necessary to hold the requested device property. This method 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.

For more information about WdfIoTargetAllocAndQueryTargetProperty, see Obtaining Information About a General I/O Target.

For more information about I/O targets, see Using I/O Targets.

Examples

The following code example calls WdfIoTargetAllocAndQueryTargetProperty to obtain the DevicePropertyFriendlyName property. After WdfIoTargetAllocAndQueryTargetProperty returns, the driver can call WdfMemoryGetBuffer to obtain a pointer to the buffer that contains the name string.

WDFMEMORY  targetName;
NTSTATUS  status;

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

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfiotarget.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)