diInstallDevice 函数 (newdev.h)

项目
02/29/2024

DiInstallDevice 函数安装一个指定的驱动程序，该驱动程序预安装在系统中存在的指定设备上的驱动程序存储中。

语法

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

参数

[in, optional] hwndParent

DiInstallDevice 用来显示与安装设备关联的任何用户界面组件的顶级窗口的句柄。此参数是可选的，可以设置为 NULL。

[in] DeviceInfoSet

包含表示指定设备的设备信息元素的设备信息集的句柄。

[in] DeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，该结构表示指定设备信息集中的指定设备。

[in, optional] DriverInfoData

指向 SP_DRVINFO_DATA 结构的指针，该结构指定要在指定设备上安装的驱动程序。此参数是可选的，可以设置为 NULL。如果此参数为 NULL，DiInstallDevice 将搜索驱动程序存储中预安装的驱动程序，以查找与指定设备最匹配的驱动程序，如果找到驱动程序，则会在指定的设备上安装驱动程序。

[in] Flags

一个 DWORD 类型的值，该值指定零或以下标志：

DIIDFLAG_SHOWSEARCHUI

如果调用方未指定驱动程序 (DriverInfoData 设置为 NULL) 并且 DiInstallDevice 不会找到与指定设备匹配的预安装驱动程序。相反， DiInstallDevice 会显示设备的“查找新硬件”向导。

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice 不会启动完成安装向导页或完成安装操作。 DiInstallDevice 的调用方必须启动这些操作。仅当调用方要求在调用方提供的用户界面组件的上下文中调用完成安装向导页时，调用方才应指定此标志。

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice 尝试在指定的设备上安装 null 驱动程序。如果设置了此标志， DiInstallDevice 不使用 DriverInfoData 参数。 DiInstallDevice 删除所有设备设置，如果设备无法在原始模式下运行，则函数会将设备的状态设置为 CM_PROB_FAILED_INSTALL。如果 DiInstallDevice 无法安装 null 驱动程序，则设备的结果状态与设备首次连接到计算机时相同，并且 Windows 未找到该设备的驱动程序。

DIIDFLAG_INSTALLCOPYINFDRIVERS

通过 CopyINF 指令指定的任何其他 INF 文件都将安装在它适用的任何设备上。安装其他 INF 时出现的任何失败都不会导致主 INF 的安装失败。

[out, optional] NeedReboot

指向 BOOL 类型的值的指针， DiInstallDevice 设置该值指示是否需要重启系统才能完成安装。此参数是可选的，可以设置为 NULL。如果提供了此参数，并且需要重启系统才能完成安装， 则 DiInstallDevice 会将该值设置为 TRUE。在这种情况下，调用方负责重启系统。如果提供了此参数且不需要重启系统， DiInstallDevice 会将此参数设置为 FALSE。如果此参数为 NULL ，并且需要重启系统才能完成安装， 则 DiInstallDevice 将显示系统重启对话框。

返回值

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

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

注解

只有在需要在特定设备上安装特定驱动程序时，才调用 DiInstallDevice 。否则，请使用 UpdateDriverForPlugAndPlayDevices 或 DiInstallDriver 为设备安装驱动程序。有关在设备上安装驱动程序时要调用的函数的详细信息，请参阅简化驱动程序安装的 SetupAPI 函数。

在调用 DiInstallDevice 之前，调用方必须获取 SP_DEVINFO_DATA 结构以指定设备，还可以获取 SP_DRVINFO_DATA 结构来指定设备的驱动程序。

若要创建包含指定设备的设备信息集并获取设备的 SP_DEVINFO_DATA 结构，请执行以下操作之一：

调用 SetupDiGetClassDevs 检索包含该设备的设备信息集，然后调用 SetupDiEnumDeviceInfo 以枚举设备信息集中的设备。每次调用时， SetupDiEnumDeviceInfo 都会返回一个 SP_DEVINFO_DATA 结构，该结构表示设备信息集中的枚举设备。若要获取有关枚举设备的特定信息，请调用 SetupDiGetDeviceProperty 并提供 SetupDiEnumDeviceInfo 返回的SP_DEVINFO_DATA结构。
- 或 -
调用 SetupDiOpenDeviceInfo ，将具有已知设备实例 ID 的设备添加到设备信息集。 SetupDiOpenDeviceInfo 返回 SP_DEVINFO_DATA 结构，该结构表示设备信息集中的设备。

若要检索所选驱动程序的SP_DRVINFO_DATA 结构，请调用 SetupDiBuildDriverInfoList 以生成设备的驱动程序列表，然后调用 SetupDiEnumDriverInfo 以枚举设备的驱动程序列表元素。对于每个枚举的驱动程序， SetupDiEnumDriverInfo 检索标识驱动程序 的SP_DRVINFO_DATA 结构。还可以调用 SetupDiGetDriverInfoDetail 来检索有关枚举驱动程序的其他详细信息。

通常，安装应用程序应将 NeedReboot 设置为 NULL。这可确保 DiInstallDevice 在需要重启以完成安装时提示用户重启系统。应用程序应仅在以下情况下提供 NeedReboot 指针：

应用程序必须多次调用 DiInstallDevice 才能完成安装。在这种情况下，应用程序应记录对 DiInstallDevice 的任何调用是否返回 TRUENeedReboot 值，如果是，则提示用户在最终调用 DiInstallDevice 返回后重启系统。
应用程序必须执行所需的操作，而不是调用 DiInstallDevice，然后系统重启。如果需要重启系统，应用程序应完成所需的操作，然后提示用户重启系统。
应用程序是类安装程序，在这种情况下，类安装程序应在设备的 SP_DEVINSTALL_PARAMS 结构的 Flags 成员中设置 DI_NEEDREBOOT 标志。

要求

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