Share via

DiRollbackDriver 函数 (newdev.h)

  • 项目

DiRollbackDriver 函数回滚在指定设备上安装的驱动程序。

语法

BOOL DiRollbackDriver(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

参数

[in] DeviceInfoSet

设备信息集的句柄，其中包含表示执行驱动程序回滚的设备的设备信息元素。

[in] DeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，该结构表示执行驱动程序回滚的指定设备信息集中的特定设备。

[in, optional] hwndParent

DiRollbackDriver 用于显示与指定设备的驱动程序回滚关联的任何用户界面组件的顶级窗口的句柄。 此参数是可选的，可以设置为 NULL。

[in] Flags

类型为 DWORD 的值，可设置为零或ROLLBACK_FLAG_NO_UI。

通常，此标志应设置为零，在这种情况下 ，DiRollbackDriver 不会禁止显示与驱动程序回滚关联的默认用户界面组件。 但是，如果此标志设置为 ROLLBACK_FLAG_NO_UI，DiRollbackDriver 将禁止显示与驱动程序回滚关联的用户界面组件。

[out, optional] NeedReboot

指向 BOOL 类型的值的指针， DiRollbackDriver 设置该值指示是否需要重启系统才能完成回滚。 此参数是可选的，可以为 NULL。

如果提供了 参数，并且需要重启系统才能完成回滚， DiRollbackDriver 会将值设置为 TRUE。 在这种情况下，调用方必须提示用户重启系统。 如果提供了此参数，并且不需要系统重启即可完成安装， DiRollbackDriver 会将值设置为 FALSE。

如果 参数为 NULL 并且需要重启系统才能完成回滚， DiRollbackDriver 将显示系统重启对话框。

有关此参数的详细信息，请参阅以下 “备注” 部分。

返回值

如果函数成功回滚设备的驱动程序，DiRollbackDriver 将返回 TRUE;否则，DiRollbackDriver 将返回 FALSE，并且可以通过调用 GetLastError 来检索记录的错误。 GetLastError 可能返回的一些更常见的错误值如下所示：

返回代码 说明
ERROR_ACCESS_DENIED
 调用方没有管理员权限。 默认情况下，Windows 要求调用方具有管理员权限才能回滚 驱动程序包。
ERROR_IN_WOW64
 调用应用程序是尝试在 64 位环境中执行的 32 位应用程序，这是不允许的。 有关详细信息，请参阅 在 64 位系统上安装设备。
ERROR_INVALID_FLAGS
 为 Flags 指定的值不等于零或ROLLBACK_FLAG_NO_UI。
ERROR_NO_MORE_ITEMS
 未为设备设置备份驱动程序。

注解

如果为设备设置了以前安装的备份驱动程序，则设备的驱动程序回滚会将设备上当前安装的驱动程序替换为备份驱动程序。 Windows 最多为设备维护一个备份驱动程序。 在设备上成功安装驱动程序后，Windows 立即将驱动程序设置为设备的备份驱动程序，并且 Windows 确定设备正常运行。 但是，如果驱动程序未在设备上成功安装，或者设备在安装后无法正常工作，则 Windows 不会将驱动程序设置为设备的备份驱动程序。 有关驱动程序回滚的详细信息，请参阅帮助和支持中心中的设备管理器。

如果指定的设备具有备份驱动程序， DiRollbackDriver 将执行以下操作：

  1. 如果 Flags 设置为零， DiRollbackDriver 会提示用户确认是否应安装备份驱动程序。 否则，如果 Flags 设置为 ROLLBACK_FLAG_NO_UI，DiRollbackDriver 将安装备份驱动程序，而不提示用户确认备份驱动程序的安装。
  2. DiRollbackDriver 安装备份驱动程序。 如果备份驱动程序是否比设备上当前安装的驱动程序更适合设备，则安装驱动程序。
  3. 如果被备份驱动程序替换的驱动程序不是收件箱驱动程序，并且未安装在系统的任何其他设备上， DiRollbackDriver 将从系统中删除该驱动程序。 DiRollbackDriver 从系统中删除驱动程序，因为假定用户仅在驱动程序出现问题时才会替换驱动程序。
如果指定的设备没有备份驱动程序， DiRollbackDriver 调用 SetLastError 以设置错误ERROR_NO_MORE_ITEMS，不会删除当前安装的驱动程序，并返回 FALSE。

通常，安装应用程序应将 NeedReboot 设置为 NULL ，以便在需要重启才能完成回滚时系统自动启动系统重启。 应用程序应仅在以下情况下提供 NeedReboot 指针：

  • 应用程序必须多次调用 DiRollbackDriver 才能完成安装。 在这种情况下，应用程序应记录对 DiRollbackDriver 的任何调用是否返回 TRUENeedReboot 值，如果是，则提示用户在最终调用 DiRollbackDriver 返回后重启系统。
  • 应用程序必须执行所需的操作，而不是调用 DiRollbackDriver，然后才能重启系统。 如果需要重启系统，应用程序应完成所需的操作，然后提示用户重启系统。
若要为设备安装新驱动程序而不是回滚设备的驱动程序，请调用 DiInstallDriver 或 UpdateDriverForPlugAndPlayDevices。

要求

要求 值
最低受支持的客户端 在 Windows Vista 和更高版本的 Windows 中可用。
目标平台 桌面
标头 newdev.h (包括 Newdev.h)
Library Newdev.lib
DLL Newdev.dll

另请参阅

DiInstallDriver

UpdateDriverForPlugAndPlayDevices