DiUninstallDevice 函数 (newdev.h)

DiUninstallDevice 函数卸载设备，并从系统中删除其设备节点 (devnode) 。 这与将 SetupDiCallClassInstaller 与 DIF_REMOVE 代码配合使用不同，因为它除了尝试卸载调用时存在的子开发节点外，还会尝试卸载设备节点。

在Windows 8调用时不存在的任何子设备都不会卸载。 但是，从Windows 8开始，将卸载调用时不存在的任何子设备。

语法

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

参数

[in] hwndParent

顶级窗口的句柄，用于显示与设备的卸载请求关联的任何用户界面组件。 此参数是可选的，可以设置为 NULL。

[in] DeviceInfoSet

包含 设备信息元素的设备信息集 的句柄。 此元素表示要通过此调用卸载的设备。

[in] DeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，该结构表示执行卸载请求的指定设备信息集中的指定设备。

[in] Flags

类型为 DWORD 的值，该值指定设备卸载标志。 从 Windows 7 开始，此参数必须设置为零。

[out, optional] NeedReboot

指向 BOOL 类型的值的指针， DiUninstallDevice 设置该值指示是否需要重启系统才能完成设备卸载请求。 此参数是可选的，可以设置为 NULL。

如果提供了 参数并且需要重启系统， 则 DiUninstallDevice 会将值设置为 TRUE。 在这种情况下，应用程序必须提示用户重启系统。 如果提供了此参数并且不需要重启系统， 则 DiUninstallDevice 会将值设置为 FALSE。

如果此参数为 NULL 并且需要重启系统才能完成设备卸载， DiUninstallDevice 将显示系统重启对话框。

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

返回值

如果函数成功卸载表示设备的顶级设备节点，DiUninstallDevice 将返回 TRUE。 否则， DiUninstallDevice 返回 FALSE，可以通过调用 GetLastError 来检索记录的错误。 以下列表显示了 GetLastError 可能为此 API 返回的一些更常见的错误值：

返回代码	说明
ERROR_ACCESS_DENIED	调用方没有管理员权限。 默认情况下，Windows 要求调用方具有管理员权限才能卸载设备。
ERROR_INVALID_FLAGS	为 Flags 参数指定的值不等于零。

 

注意 返回值并不表示删除所有子开发节点都成功或失败。 从 Windows Vista 开始， Setupapi.dev.log 文件中提供了 有关删除子开发节点的状态的信息。 有关此文件的详细信息，请参阅 安装程序API 文本日志。

 

注解

与 DIF_REMOVE 代码一起使用时，DiUninstallDevice 执行与 SetupDiCallClassInstaller 相同的功能。 关键区别在于也会删除顶级设备的子开发节点。 DiUninstallDevice 仅当无法卸载顶级设备节点时返回失败，这与与 DIF_REMOVE 代码一起使用时的 SetupDiCallClassInstaller 的行为一致。 有关子 devnode 卸载是否成功的详细信息，请参阅 Setupapi.dev.log 文件中。

通过提供设备 信息集 （包括引用的设备）和特定设备的 SP_DEVINFO_DATA 结构来指定要卸载的设备。 这些参数在 DeviceInfoSet 和 DeviceInfoData 参数中提供。

若要创建包含指定设备的设备信息集并获取 设备的SP_DEVINFO_DATA 结构，请完成以下任务之一：

• 调用 SetupDiGetClassDevs 检索包含该设备的设备信息集，然后调用 SetupDiEnumDeviceInfo 以枚举设备信息集中的设备。 每次调用时， SetupDiEnumDeviceInfo 都会返回一个 SP_DEVINFO_DATA 结构，该结构表示设备信息集中的枚举设备。

  若要获取有关枚举设备的特定信息，请调用 SetupDiGetDeviceProperty 并提供 SetupDiEnumDeviceInfo 返回的SP_DEVINFO_DATA结构。

• 调用 SetupDiEnumDeviceInfo ，将具有已知设备实例 ID 的设备添加到设备信息集。 SetupDiOpenDeviceInfo 返回一个 SP_DEVINFO_DATA 结构，该结构表示设备信息集中的设备。

如果设备卸载请求需要重启计算机， DiUninstallDevice 会提示用户重启系统（如果 NeedReboot 参数设置为 NULL）。 如果应用程序正在使用任何用户界面窗口，则应将 hwndParent 参数设置为该窗口句柄的值。

但是，如果应用程序管理所需的系统重启通知，则必须将 NeedReboot 参数设置为非 NULL 值。 DiUninstallDevice 将 NeedReboot 参数设置为 TRUE 或 FALSE，具体取决于是否需要重启系统。

以下列表显示了应用程序为何可能管理系统重启的示例：

• 应用程序必须卸载多个设备。 卸载所有设备后，如果对 DiUninstallDevice 的任何调用在 NeedReboot 参数中返回 TRUE，应用程序应提示用户重启系统。
• 应用程序需要执行一些其他操作，然后才能重启系统。 如果需要重启系统，应用程序应完成所需的操作，然后提示用户重启系统。
• 应用程序是类安装程序。 在这种情况下，类安装程序应在设备的 SP_DEVINSTALL_PARAMS 结构的 Flags 成员中设置 DI_NEEDREBOOT 标志。

要求

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

另请参阅

DIF_REMOVE

设备信息集

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS

SetupDiCallClassInstaller

SetupDiEnumDeviceInfo

SetupDiGetClassDevs

SetupDiGetDeviceProperty