WdfDeviceInitSetReleaseHardwareOrderOnFailure function (wdfdevice.h)
[Applies to KMDF and UMDF]
The WdfDeviceInitSetReleaseHardwareOrderOnFailure method specifies whether the framework calls the driver's EvtDeviceReleaseHardware callback function immediately after device failure, or waits until all child devices have been removed.
Syntax
void WdfDeviceInitSetReleaseHardwareOrderOnFailure(
[in] PWDFDEVICE_INIT DeviceInit,
[in] WDF_RELEASE_HARDWARE_ORDER_ON_FAILURE ReleaseHardwareOrderOnFailure
);
Parameters
[in] DeviceInit
A pointer to a WDFDEVICE_INIT structure.
[in] ReleaseHardwareOrderOnFailure
A WDF_RELEASE_HARDWARE_ORDER_ON_FAILURE-typed enumerator that specifies when the framework calls the driver's EvtDeviceReleaseHardware callback function.
Return value
None
Remarks
Typically, the framework calls a driver's EvtDeviceReleaseHardware callback function after it has called the EvtDeviceReleaseHardware function for all child devices that the driver enumerates.
In the event of a device power-up or power-down failure, however, the framework might call the driver's EvtDeviceReleaseHardware before it has called the EvtDeviceReleaseHardware functions for all child devices.
To override this default behavior, a driver can call WdfDeviceInitSetReleaseHardwareOrderOnFailure to specify that, even in device failure scenarios, the framework should always wait to call its EvtDeviceReleaseHardware function until it has called the EvtDeviceReleaseHardware functions of the child devices.
For example, a bus driver that performs hardware access on behalf of its child devices could use this technique to ensure that its child devices do not request access to hardware after the framework has called the bus driver's EvtDeviceReleaseHardware callback function.
If a driver calls WdfDeviceInitSetReleaseHardwareOrderOnFailure, it must do so before it calls WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.
Examples
The following code example shows how a bus driver can request that the framework wait to call its EvtDeviceReleaseHardware callback function until all of its child devices have been removed.
WdfDeviceInitSetReleaseHardwareOrderOnFailure(
DeviceInit,
WdfReleaseHardwareOrderOnFailureAfterDescendants
);
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.11 |
| Minimum UMDF version | 2.0 |
| Header | wdfdevice.h (include Wdf.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <= DISPATCH_LEVEL |
| DDI compliance rules | DriverCreate(kmdf) |