EvtDeviceFilterAddResourceRequirements function

[Applies to KMDF only]

A driver's EvtDeviceFilterAddResourceRequirements event callback function can add resources to a set of hardware resource requirements before the system assigns resources to a device.

Syntax

EVT_WDF_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtDeviceFilterAddResourceRequirements;

NTSTATUS EvtDeviceFilterAddResourceRequirements(
  _In_  WDFDEVICE Device,
  _In_  WDFIORESREQLIST IoResourceRequirementsList
)
{ ... }

Parameters

Device [in]

A handle to the framework device object to which resources will be assigned.

IoResourceRequirementsList [in]

A handle to a resource-requirements-list object, which represents the device's resource requirements list.

Return value

If the driver encountered no errors it must return STATUS_SUCCESS. Otherwise it must return an NTSTATUS value that NT_SUCCESS evaluates as FALSE.

For more information about return values, see Reporting Device Failures.

Remarks

Framework-based function drivers can provide an EvtDeviceFilterAddResourceRequirements callback function. To register this callback function, drivers call WdfFdoInitSetEventCallbacks.

When the framework calls a driver's EvtDeviceFilterAddResourceRequirements callback function, the driver can add resource descriptors to a logical configuration, and it can provide additional logical configurations. These added items represent resources that the function driver requires to make the device operational.

If a driver's EvtDeviceFilterAddResourceRequirements callback function adds items to a device's resource requirements list, and if the PnP manager assigns the resources to the device's requirements list, the driver's EvtDeviceRemoveAddedResources callback function must remove the added resources from the device's resource list.

To add items to a resource requirements list, the driver calls framework resource-requirements-list object methods and framework resource-range-list object methods, which add resources to the resource-requirements-list object that is represented by the IoResourceRequirementsList parameter.

For more information about the EvtDeviceFilterAddResourceRequirements callback function, see Modifying a Resource Requirements List.

For more information about hardware resources and resource requirements lists, see Hardware Resources for Framework-Based Drivers.

Examples

To define an EvtDeviceFilterAddResourceRequirements 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 EvtDeviceFilterAddResourceRequirements callback function that is named MyDeviceFilterAddResourceRequirements, use the EVT_WDF_DEVICE_FILTER_RESOURCE_REQUIREMENTS type as shown in this code example:

EVT_WDF_DEVICE_FILTER_RESOURCE_REQUIREMENTS  MyDeviceFilterAddResourceRequirements;

Then, implement your callback function as follows:

_Use_decl_annotations_
NTSTATUS
 MyDeviceFilterAddResourceRequirements (
    WDFDEVICE  Device,
    WDFIORESREQLIST  IoResourceRequirementsList
    )
  {...}

The EVT_WDF_DEVICE_FILTER_RESOURCE_REQUIREMENTS function type is defined in the Wdffdo.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_FILTER_RESOURCE_REQUIREMENTS 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

See also

EvtDeviceFilterRemoveResourceRequirements

EvtDeviceRemoveAddedResources

Send comments about this topic to Microsoft