WdfDeviceSetFailed function

[Applies to KMDF and UMDF]

The WdfDeviceSetFailed method informs the framework that the driver encountered a hardware or software error that is associated with a specified device.

Syntax

VOID WdfDeviceSetFailed(
  _In_ WDFDEVICE                Device,
  _In_ WDF_DEVICE_FAILED_ACTION FailedAction
);

Parameters

Device

A handle to a framework device object.

FailedAction

A WDF_DEVICE_FAILED_ACTION-typed enumerator that indicates whether the framework should attempt to reload the specified device's drivers.

Return Value

None.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

If a driver encounters an unrecoverable hardware or software error, it must call WdfDeviceSetFailed so that the system can unload the device's drivers.

Starting in UMDF version 2.15, a UMDF driver can request that the the underlying bus driver re-enumerate it by calling WdfDeviceSetFailed with FailedAction set to WdfDeviceFailedAttemptRestart. The bus driver must support the GUID_REENUMERATE_SELF_INTERFACE_STANDARD interface.

Alternatively, a UMDF driver can set FailedAction to WdfDeviceFailedNoRestart.

For more information about WdfDeviceSetFailed, see Reporting Device Failures.

Examples

The following code example informs the framework that a failure has occurred. If the specified device's drivers are not supporting other devices, the framework will unload the drivers and then attempt to reload them.

WdfDeviceSetFailed(
                   device,
                   WdfDeviceFailedAttemptRestart
                   );

Requirements

   
Target Platform Universal
Minimum KMDF version 1.0
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, KmdfIrql, KmdfIrql2