WdfDeviceAddQueryInterface function (wdfqueryinterface.h)

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

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

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

See also

EvtDevicePrepareHardware

EvtDriverDeviceAdd

WDF_QUERY_INTERFACE_CONFIG

WDF_QUERY_INTERFACE_CONFIG_INIT

WdfDeviceInterfaceDereferenceNoOp

WdfDeviceInterfaceReferenceNoOp

WdfFdoQueryForInterface