DiRollbackDriver function (newdev.h)
The DiRollbackDriver function rolls back the driver that is installed on a specified device.
Syntax
BOOL DiRollbackDriver(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in, optional] HWND hwndParent,
[in] DWORD Flags,
[out, optional] PBOOL NeedReboot
);
Parameters
[in] DeviceInfoSet
A handle to the device information set that contains a device information element that represents the device for which driver rollback is performed.
[in] DeviceInfoData
A pointer to an SP_DEVINFO_DATA structure that represents the specific device in the specified device information set for which driver rollback is performed.
[in, optional] hwndParent
A handle to the top-level window that DiRollbackDriver uses to display any user interface component that is associated with a driver rollback for the specified device. This parameter is optional and can be set to NULL.
[in] Flags
A value of type DWORD that can be set to zero or ROLLBACK_FLAG_NO_UI.
Typically, this flag should be set to zero, in which case DiRollbackDriver does not suppress the default user interface components that are associated with a driver rollback. However, if this flag is set to ROLLBACK_FLAG_NO_UI, DiRollbackDriver suppresses the display of user interface components that are associated with a driver rollback.
[out, optional] NeedReboot
A pointer to a value of type BOOL that DiRollbackDriver sets to indicate whether a system restart is required to complete the rollback. This parameter is optional and can be NULL.
If the parameter is supplied and a system restart is required to complete the rollback, DiRollbackDriver sets the value to TRUE. In this case, the caller must prompt the user to restart the system. If this parameter is supplied and a system restart is not required to complete the installation, DiRollbackDriver sets the value to FALSE.
If the parameter is NULL and a system restart is required to complete the rollback, DiRollbackDriver displays a system restart dialog box.
For more information about this parameter, see the following Remarks section.
Return value
DiRollbackDriver returns TRUE if the function successfully rolled back the driver for the device; otherwise, DiRollbackDriver returns FALSE and the logged error can be retrieved by making a call to GetLastError. Some of the more common error values that GetLastError might return are as follows:
| Return code | Description |
|---|---|
|
The caller does not have Administrator privileges. By default, Windows requires that the caller have Administrator privileges to roll back a driver package. |
|
The calling application is a 32-bit application that is attempting to execute in a 64-bit environment, which is not allowed. For more information, see Installing Devices on 64-Bit Systems. |
|
The value specified for Flags is not equal to zero or ROLLBACK_FLAG_NO_UI. |
|
A backup driver is not set for the device. |
Remarks
If a previously installed backup driver is set for a device, a driver rollback for the device replaces the driver that is currently installed on the device with the backup driver. Windows maintains at most one backup driver for a device. Windows sets a driver as the backup driver for a device immediately after the driver is successfully installed on the device and Windows determines that the device is functioning correctly. However, if a driver does not install successfully on a device or the device does not function correctly after the installation, Windows does not set the driver as the backup driver for the device. For more information about driver rollback, see information about Device Manager in Help and Support Center.
If the specified device has a backup driver, DiRollbackDriver performs the following operations:
- If Flags is set to zero, DiRollbackDriver prompts the user to confirm whether the backup driver should be installed. Otherwise, if Flags is set to ROLLBACK_FLAG_NO_UI, DiRollbackDriver installs the backup driver without prompting the user to confirm the installation of the backup driver.
- DiRollbackDriver installs the backup driver. The driver is installed whether the backup driver is a better match for the device than the driver that is currently installed on the device.
- If the driver that is replaced by the backup driver is not an inbox driver and is not installed on any other devices in the system, DiRollbackDriver removes the driver from the system. DiRollbackDriver removes the driver from the system because it is assumed that a user will replace a driver only if there is a problem with the driver.
In general, installation applications should set NeedReboot to NULL so that the system will automatically initiate a system restart if a restart is required to complete the rollback. An application should supply a NeedReboot pointer only in the following cases:
- The application must call DiRollbackDriver several times to complete an installation. In this case, the application should record whether a TRUENeedReboot value is returned by any of the calls to DiRollbackDriver and, if so, prompt the user to restart the system after the final call to DiRollbackDriver returns.
- The application must perform required operations, other than calling DiRollbackDriver, before a system restart should occur. If a system restart is required, the application should finish the required operations and then prompt the user to restart the system.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows Vista and later versions of Windows. |
| Target Platform | Desktop |
| Header | newdev.h (include Newdev.h) |
| Library | Newdev.lib |
| DLL | Newdev.dll |