Collapse the table of content
Expand the table of content

EvtDeviceRelationsQuery function

[Applies to KMDF and UMDF]

A driver's EvtDeviceRelationsQuery event callback reports changes in the relationships among devices that are supported by the driver.



VOID EvtDeviceRelationsQuery(
  _In_ WDFDEVICE            Device,
{ ... }


Device [in]

A handle to a framework device object.

RelationType [in]

A DEVICE_RELATION_TYPE-typed enumerator value. The DEVICE_RELATION_TYPE enumeration is defined in wdm.h.

Return value



To register the EvtDeviceRelationsQuery callback function, a driver must call WdfDeviceInitSetPnpPowerEventCallbacks.

Most framework-based drivers do not need to provide this callback function.

During system initialization, the Plug and Play manager enumerates all of the devices on the system by sending an IRP_MN_QUERY_DEVICE_RELATIONS request to the driver stack. If a framework-based driver has registered an EvtDeviceRelationsQuery callback function, the framework calls it. The function driver for the bus must report all of the child devices that are attached to the bus.

Additionally, after the framework calls the IoInvalidateDeviceRelations routine to report a changed relationship among the devices on the driver's bus, the Plug and Play manager sends another IRP_MN_QUERY_DEVICE_RELATIONS request to the driver stack. The framework then calls the driver's EvtDeviceRelationsQuery callback function so that the driver can provide details about the change.

The type of work that a driver must do depends on the value received for the RelationType parameter. The value can be one of the following:


Most framework-based drivers do not report bus relations in an EvtDeviceRelationsQuery callback function. Instead, the drivers follow the guidelines that are described in Enumerating the Devices on a Bus.


Most framework-based drivers do not report ejection relations in an EvtDeviceRelationsQuery callback function. Instead, the driver for the device's bus calls WdfPdoAddEjectionRelationsPhysicalDevice and WdfPdoRemoveEjectionRelationsPhysicalDevice.


Most framework-based drivers do not report removal relations in an EvtDeviceRelationsQuery callback function. Instead, the drivers call WdfDeviceAddRemovalRelationsPhysicalDevice and WdfDeviceRemoveRemovalRelationsPhysicalDevice.


Framework-based drivers do not have to report a device's target relation. Instead, the framework handles this request.

The framework can call the EvtDeviceRelationsQuery callback function with a RelationType value of EjectionRelations or RemovalRelations even if the device is being removed.


To define an EvtDeviceRelationsQuery callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtDeviceRelationsQuery callback function that is named MyDeviceRelationsQuery, use the EVT_WDF_DEVICE_RELATIONS_QUERY type as shown in this code example:


Then, implement your callback function as follows:

 MyDeviceRelationsQuery (
    WDFDEVICE  Device,

The EVT_WDF_DEVICE_RELATIONS_QUERY function type is defined in the Wdfdevice.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_DEVICE_RELATIONS_QUERY function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.


Target platform


Minimum KMDF version


Minimum UMDF version



Wdfdevice.h (include Wdf.h)





Send comments about this topic to Microsoft

© 2015 Microsoft