WdfIoTargetQueryTargetProperty function (wdfiotarget.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfIoTargetQueryTargetProperty method retrieves a specified device property for a specified I/O target.

Syntax

NTSTATUS WdfIoTargetQueryTargetProperty(
  [in]            WDFIOTARGET              IoTarget,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

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] BufferLength

The size, in bytes, of the buffer that PropertyBuffer points to.

[out, optional] PropertyBuffer

A pointer to a caller-allocated buffer that receives the requested device property information. This pointer can be NULL if BufferLength is zero.

[out] ResultLength

A pointer to a location that, on return, contains the size, in bytes, of the information that WdfIoTargetQueryTargetProperty stored in the buffer that PropertyBuffer points to. If WdfIoTargetQueryTargetProperty returns STATUS_BUFFER_TOO_SMALL, this location receives the required buffer size.

Return value

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

Return code	Description
STATUS_BUFFER_TOO_SMALL	The buffer that the PropertyBuffer parameter pointed to was too small to receive the requested information.
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

Before drivers receive device property data, they typically call the WdfIoTargetQueryTargetProperty method to obtain the required buffer size. For some properties, the data size can change between when the required size is returned and when the driver calls WdfIoTargetQueryTargetProperty again. Therefore, drivers should call WdfIoTargetQueryTargetProperty inside a loop that executes until the return status is not STATUS_BUFFER_TOO_SMALL.

Instead of calling WdfIoTargetQueryTargetProperty, your driver can call WdfIoTargetAllocAndQueryTargetProperty, which allocates a buffer and places the property information in the buffer.

For more information about WdfIoTargetQueryTargetProperty, 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 obtains a device's DevicePropertyUINumber property. The example calls WdfIoTargetQueryTargetProperty instead of WdfIoTargetAllocAndQueryTargetProperty because the length of a UI number is known.

ULONG targetUINumber, resultLength;
NTSTATUS status;

status = WdfIoTargetQueryTargetProperty(
                                        target,
                                        DevicePropertyUINumber,
                                        sizeof(targetNumber),
                                        &targetUINumber,
                                        &resultLength
                                        );

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)