The WdfDeviceAddQueryInterface method creates a driver-defined interface that other drivers can query and use.

WDFAPI NTSTATUS
  WdfDeviceAddQueryInterface(
    IN WDFDEVICE  Device,
    IN PWDF_QUERY_INTERFACE_CONFIG  InterfaceConfig
    );

Parameters

Device

A handle to a framework device object.

InterfaceConfig

A pointer to a driver-allocated WDF_QUERY_INTERFACE_CONFIG structure that describes the interface.

Return Value

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

STATUS_INVALID_DEVICE_REQUEST

The method was called at the wrong IRQL.

STATUS_INVALID_PARAMETER

An input parameter (possibly including members of the WDF_QUERY_INTERFACE_CONFIG structure) was invalid.

STATUS_INFO_LENGTH_MISMATCH

The size of the WDF_QUERY_INTERFACE_CONFIG structure was incorrect.

STATUS_INSUFFICIENT_RESOURCES

There was insufficient memory.

For a list of additional return values, see Framework Object Creation Errors.

This method might also return other NTSTATUS values.

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

Comments

Drivers that create driver-defined interfaces typically call WdfDeviceAddQueryInterface from within an EvtDriverDeviceAdd or EvtDevicePrepareHardware callback function.

After a driver calls WdfDeviceAddQueryInterface to create a driver-defined interface, another framework-based driver can access the interface by calling WdfFdoQueryForInterface.

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

Example

The following code example is from the Toaster sample bus driver. This example creates a driver-defined interface that uses the toaster sample's TOASTER_INTERFACE_STANDARD structure.

typedef struct _TOASTER_INTERFACE_STANDARD {
  INTERFACE  InterfaceHeader;
  PTOASTER_GET_CRISPINESS_LEVEL  GetCrispinessLevel;
  PTOASTER_SET_CRISPINESS_LEVEL  SetCrispinessLevel;
  PTOASTER_IS_CHILD_PROTECTED  IsSafetyLockEnabled;
} TOASTER_INTERFACE_STANDARD, *PTOASTER_INTERFACE_STANDARD;

TOASTER_INTERFACE_STANDARD  ToasterInterface;
WDF_QUERY_INTERFACE_CONFIG  qiConfig;

//
// Initialize the ToasterInterface structure.
//
RtlZeroMemory(
              &ToasterInterface,
              sizeof(ToasterInterface)
              );

ToasterInterface.InterfaceHeader.Size = sizeof(ToasterInterface);
ToasterInterface.InterfaceHeader.Version = 1;
ToasterInterface.InterfaceHeader.Context = (PVOID)hChild;

ToasterInterface.InterfaceHeader.InterfaceReference =
        WdfDeviceInterfaceReferenceNoOp;
ToasterInterface.InterfaceHeader.InterfaceDereference =
        WdfDeviceInterfaceDereferenceNoOp;

ToasterInterface.GetCrispinessLevel = Bus_GetCrispinessLevel;
ToasterInterface.SetCrispinessLevel = Bus_SetCrispinessLevel;
ToasterInterface.IsSafetyLockEnabled = Bus_IsSafetyLockEnabled;

//
// Initialize the qiConfig structure.
//
WDF_QUERY_INTERFACE_CONFIG_INIT(
                                &qiConfig,
                                (PINTERFACE)&ToasterInterface,
                                &GUID_TOASTER_INTERFACE_STANDARD,
                                NULL
                                );

//
// Create the interface.
//
status = WdfDeviceAddQueryInterface(
                                    hChild,
                                    &qiConfig
                                    );
if (!NT_SUCCESS(status)) {
    return status;
}

Requirements

Versions: The WdfDeviceAddQueryInterface method is available in version 1.0 and later versions of KMDF.

IRQL: PASSIVE_LEVEL

Headers: Declared in WdfQueryInterface.h. Include Wdf.h.

See Also

WDF_QUERY_INTERFACE_CONFIG_INIT, WdfDeviceInterfaceReferenceNoOp, WdfDeviceInterfaceDereferenceNoOp, EvtDevicePrepareHardware, EvtDriverDeviceAdd, WDF_QUERY_INTERFACE_CONFIG, WdfFdoQueryForInterface