A driver's EvtDeviceProcessQueryInterfaceRequest event callback function examines another driver's request for access to a driver-defined interface, before the framework passes the interface to the requesting driver.

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  EvtDeviceProcessQueryInterfaceRequest;

NTSTATUS
  EvtDeviceProcessQueryInterfaceRequest (
    IN WDFDEVICE  Device,
    IN LPGUID  InterfaceType,
    IN OUT PINTERFACE  ExposedInterface,
    IN OUT PVOID  ExposedInterfaceSpecificData
    )
  {…}

You must declare the function by using the EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST type. For more information, see the following Example section.

Parameters

Device

A handle to a framework device object.

InterfaceType

A pointer to the GUID that identifies the driver-defined interface.

ExposedInterface

A pointer to an INTERFACE structure that describes the driver-defined interface and was provided by the driver that is requesting access to the interface.

ExposedInterfaceSpecificData

A pointer to additional, optional, driver-defined, interface-specific information. Framework-based drivers specify this value by providing a non-NULL InterfaceSpecificData parameter value when calling WdfFdoQueryForInterface.

Return Value

If the EvtDeviceProcessQueryInterfaceRequest callback function receives a GUID that it supports, and if the function encounters no errors, it must return STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE. The framework continues passing the request down the stack to see if additional drivers also support the interface.

The EvtDeviceProcessQueryInterfaceRequest callback function must return STATUS_NOT_SUPPORTED if it determines that, for a particular case, it will not service the interface. The framework continues passing the request down the stack to see if another driver supports the interface. For more information about this situation, see the following Comments section.

If the callback function encounters an error, it must return a status value for which NT_SUCCESS(status) equals FALSE. The framework fails the other driver's request for the interface and does not pass the request down the stack.

Comments

Framework-based drivers register an EvtDeviceProcessQueryInterfaceRequest event callback function by calling WdfDeviceAddQueryInterface.

If the driver-defined interface supports only one-way communication and sets the ImportInterface member of the WDF_QUERY_INTERFACE_CONFIG structure that describes the interface to FALSE, the EvtDeviceProcessQueryInterfaceRequest callback function is optional. When another driver calls WdfFdoQueryForInterface, the framework copies the driver-defined interface values into the requesting driver's INTERFACE structure and then calls the callback function. For one-way communication, you need to provide a callback function only if you want the driver to examine, and possibly modify, the interface values before the framework returns them to the requesting driver.

Your driver must provide an EvtDeviceProcessQueryInterfaceRequest event callback function if the driver defines an interface that supports two-way communication (and sets the ImportInterface member of the WDF_QUERY_INTERFACE_CONFIG structure to TRUE). The callback function is required because, if ImportInterface is TRUE and another driver calls WdfFdoQueryForInterface, the framework does not copy the driver-defined interface into the requesting driver's interface structure. Instead, the callback function must update the requesting driver's interface structure.

The callback function can modify the interface. In particular, it can:

• Change any value in any member of the interface.
• Allocate a dynamic instance-specific context by modifying the Context member of the INTERFACE structure.

The framework calls your driver's EvtDeviceProcessQueryInterfaceRequest callback functions only for GUIDs that the driver has registered by calling WdfDeviceAddQueryInterface. Therefore, these callback functions do not use the STATUS_NOT_SUPPORTED return value to report unexpected GUIDs. Instead, a EvtDeviceProcessQueryInterfaceRequest callback function should return STATUS_NOT_SUPPORTED when it determines that, for a particular case, it will not handle the interface. For example, based on data that the requesting driver provides, your driver might determine that a lower-level driver should service the interface request. The STATUS_NOT_SUPPORTED return value informs the framework that your driver is not servicing the interface request, but a lower-level driver might service it.

For more information about driver-defined interfaces, see Using Driver-Defined Interfaces.

Example

To define an EvtDeviceProcessQueryInterfaceRequest callback function that is named MyDeviceProcessQueryInterfaceRequest, you must first provide a function declaration that SDV and other verification tools require, as follows:

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

Then, implement your callback function as follows:

NTSTATUS
  MyDeviceProcessQueryInterfaceRequest (
    IN WDFDEVICE  Device,
    IN LPGUID  InterfaceType,
    IN OUT PINTERFACE  ExposedInterface,
    IN OUT PVOID  ExposedInterfaceSpecificData
    )
  {…}

Requirements

Versions: The EvtDeviceProcessQueryInterfaceRequest callback function is supported by version 1.0 and later versions of KMDF.

IRQL: PASSIVE_LEVEL

Headers: Defined in WdfQueryInternface.h, as follows:

typedef NTSTATUS
  (EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST)(
    IN WDFDEVICE  Device,
    IN LPGUID  InterfaceType,
    IN OUT PINTERFACE  ExposedInterface,
    IN OUT PVOID  ExposedInterfaceSpecificData
    );

Include Wdf.h.

See Also

INTERFACE, WDF_QUERY_INTERFACE_CONFIG, WdfDeviceAddQueryInterface, WdfFdoQueryForInterface