WdfDeviceSetFailed function (wdfdevice.h)

Article
04/18/2022

[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

[in] Device

A handle to a framework device object.

[in] 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

Remarks

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

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 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

Requirement	Value
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(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via