WdfDeviceAddQueryInterface function (wdfqueryinterface.h)

Article
04/18/2022

[Applies to KMDF only]

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

Syntax

NTSTATUS WdfDeviceAddQueryInterface(
  [in] WDFDEVICE                   Device,
  [in] PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig
);

Parameters

[in] Device

A handle to a framework device object.

[in] 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:

Return code	Description
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.

Remarks

Note

WdfDeviceAddQueryInterface cannot be called for a control device.

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.

Examples

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

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfqueryinterface.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)

Share via