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.

Syntax

EVT_WDF_DEVICE_RELATIONS_QUERY EvtDeviceRelationsQuery;

VOID EvtDeviceRelationsQuery(
  _In_  WDFDEVICE Device,
  _In_  DEVICE_RELATION_TYPE RelationType
)
{ ... }

Parameters

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

None

Remarks

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:

BusRelations

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.

EjectionRelations

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.

RemovalRelations

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

TargetDeviceRelation

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.

Examples

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:

EVT_WDF_DEVICE_RELATIONS_QUERY  MyDeviceRelationsQuery;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
 MyDeviceRelationsQuery (
    WDFDEVICE  Device,
    DEVICE_RELATION_TYPE  RelationType
    )
 {...}

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.

Requirements

Send comments about this topic to Microsoft