WDF_QUERY_INTERFACE_CONFIG structure (wdfqueryinterface.h)
[Applies to KMDF only]
The WDF_QUERY_INTERFACE_CONFIG structure describes a driver-defined interface.
Syntax
typedef struct _WDF_QUERY_INTERFACE_CONFIG {
ULONG Size;
PINTERFACE Interface;
const GUID *InterfaceType;
BOOLEAN SendQueryToParentStack;
PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtDeviceProcessQueryInterfaceRequest;
BOOLEAN ImportInterface;
} WDF_QUERY_INTERFACE_CONFIG, *PWDF_QUERY_INTERFACE_CONFIG;
Members
Size
The size, in bytes, of this structure.
Interface
A pointer to an INTERFACE structure that describes the driver-defined interface.
InterfaceType
A pointer to the GUID that identifies the interface.
Note
When introducing a new version of an existing interface, create a new GUID instead of revising the Size or Version fields of the INTERFACE structure. For more info, see Using Driver-Defined Interfaces.
SendQueryToParentStack
If TRUE, and if your driver specifies a device object that represents a physical device object (PDO) when it calls WdfDeviceAddQueryInterface, the framework sends requests for the interface to the top of the parent device's driver stack. If this member is FALSE, or if the device object does not represent a PDO, the framework does not send requests to the parent device's stack. For more information, see the following Remarks section.
EvtDeviceProcessQueryInterfaceRequest
A pointer to your driver's EvtDeviceProcessQueryInterfaceRequest event callback function, which is called when another driver requests the interface.
ImportInterface
If TRUE, the interface supports two-way communication between your driver and drivers that request the interface.
If this member is FALSE, the interface supports one-way communication from your driver to drivers that request the interface.
Remarks
The WDF_QUERY_INTERFACE_CONFIG structure is used as input to the WdfDeviceAddQueryInterface method.
For each driver-defined interface that your driver exports, you must allocate a WDF_QUERY_INTERFACE_CONFIG structure that represents the interface. Other drivers can request access to the interface by calling WdfFdoQueryForInterface.
If you want your interface to support two-way communication between the requesting driver and your driver, set the ImportInterface member to TRUE. If ImportInterface is TRUE, the structure that is provided by the requesting driver can contain data that your driver can read. In this case:
- The EvtDeviceProcessQueryInterfaceRequest callback function is required, and it must initialize the interface structure that the requesting driver provides.
-
Because the EvtDeviceProcessQueryInterfaceRequest callback function provides the interface to the requesting driver, the Interface member of WDF_QUERY_INTERFACE_CONFIG can be NULL. If you provide a non-NULL pointer, the framework verifies that the size and version values that the requesting driver supplies are equal to or greater than the values in your registered INTERFACE structure. If either of these values are smaller, the framework rejects the request. If you do not provide a value for Interface, your EvtDeviceProcessQueryInterfaceRequest callback function must verify those values.
- The EvtDeviceProcessQueryInterfaceRequest callback function is optional.
- The Interface member cannot be NULL. The framework verifies that the GUID, size, and version values that the requesting driver supplies match the ones you supplied, and the framework rejects the request if the values do not match. If the values are valid, the framework initializes the interface structure that the requesting driver provides by using the values you supply for Interface.
If the Interface member is non-NULL, the framework copies the value to internal storage space. Therefore, the driver can allocate the INTERFACE structure in local, temporary storage space.
When your driver calls WdfDeviceAddQueryInterface, it can associate the interface with a framework device object that represents either a functional device object (FDO) or a physical device object (PDO). If the driver associates the interface with a PDO, it can set the SendQueryToParentStack member of the WDF_QUERY_INTERFACE_CONFIG structure to TRUE. When the framework intercepts a request for the interface, it checks the SendQueryToParentStack member and, if it is set to TRUE, the framework sends the request to the top of the driver stack of the PDO's parent. As a result, the request travels down two driver stacks: first, the stack that contains the driver that is requesting the interface and, second, the stack of the parent of the interface's device.
The framework provides two reference/dereference methods that you can use with your interfaces by specifying their addresses for the InterfaceReference and InterfaceDereference members of the INTERFACE structure. For more information about these methods, see WdfDeviceInterfaceReferenceNoOp and WdfDeviceInterfaceDereferenceNoOp.
Drivers should initialize this structure by calling WDF_QUERY_INTERFACE_CONFIG_INIT.
For more information about driver-defined interfaces, see Using Driver-Defined Interfaces.
Requirements
| Requirement | Value |
|---|---|
| Minimum KMDF version | 1.0 |
| Header | wdfqueryinterface.h (include Wdf.h) |
See also
EvtDeviceProcessQueryInterfaceRequest
WDF_QUERY_INTERFACE_CONFIG_INIT
WdfDeviceInterfaceDereferenceNoOp