WdfIoTargetQueryForInterface function (wdfiotarget.h)

[Applies to KMDF only]

The WdfIoTargetQueryForInterface method obtains access to the GUID-identified, driver-defined interface of a remote I/O target.

Syntax

NTSTATUS WdfIoTargetQueryForInterface(
  [in]           WDFIOTARGET IoTarget,
  [in]           LPCGUID     InterfaceType,
  [out]          PINTERFACE  Interface,
  [in]           USHORT      Size,
  [in]           USHORT      Version,
  [in, optional] PVOID       InterfaceSpecificData
);

Parameters

[in] IoTarget

A handle to a remote I/O target object that was obtained from a previous call to WdfIoTargetCreate.

[in] InterfaceType

A pointer to a GUID that identifies the interface.

[out] Interface

A pointer to a driver-allocated structure that receives the requested interface. This structure is defined by the driver that exports the requested interface and must begin with an INTERFACE structure.

[in] Size

The size, in bytes, of the driver-allocated structure that Interface points to.

[in] Version

The version number of the requested interface. The driver that exports the requested interface defines the format of this value.

[in, optional] InterfaceSpecificData

Additional interface-specific information. This parameter is optional and can be NULL.

Return value

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

Return code Description
STATUS_INVALID_PARAMETER
The IoTarget, InterfaceType, or Interface parameter is NULL.
STATUS_INSUFFICIENT_RESOURCES
the framework could not allocate a request to send to another driver.
 

This method also might return other NTSTATUS values.

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

Remarks

Your driver can call WdfIoTargetQueryForInterface to obtain access to a driver-defined interface that was created by a driver in a different driver stack. To access a driver-defined interface that was created by a driver that is in the same driver stack as your driver, your driver must call WdfFdoQueryForInterface.

Framework-based drivers define interfaces by calling WdfDeviceAddQueryInterface. For more information about driver-defined interfaces, see Using Driver-Defined Interfaces.

Examples

The following code example attempts to gain access to a specified remote I/O target's interface. GUID_RAWPDO_INTERFACE_STANDARD is the GUID that identifies the interface.

NTSTATUS status;
RAWPDO_INTERFACE_STANDARD busInterface;

status = WdfIoTargetQueryForInterface(
                                      IoTarget,
                                      &GUID_RAWPDO_INTERFACE_STANDARD,
                                      (PINTERFACE) &busInterface,
                                      sizeof(RAWPDO_INTERFACE_STANDARD),
                                      1,
                                      NULL
                                      );
if (!NT_SUCCESS (status)){
    return status;
}

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)

See also

INTERFACE

WdfDeviceAddQueryInterface

WdfFdoQueryForInterface

WdfIoTargetCreate