WdfIoTargetAllocAndQueryTargetProperty method

[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

IoTarget [in]

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.

DeviceProperty [in]

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

PoolType [in]

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

PropertyMemoryAttributes [in, optional]

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.

PropertyMemory [out]

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 codeDescription
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

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, KmdfIrql, KmdfIrql2

See also

DEVICE_REGISTRY_PROPERTY
POOL_TYPE
WDF_OBJECT_ATTRIBUTES
WdfDeviceAllocAndQueryProperty
WdfDeviceGetIoTarget
WdfIoTargetCreate
WdfIoTargetQueryTargetProperty
WdfMemoryGetBuffer

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft