DiInstallDriverW 函数 (newdev.h)

  • 项目

DiInstallDriver 函数在驱动程序存储中预安装驱动程序，然后在驱动程序支持的系统中存在的设备上安装驱动程序。

语法

BOOL DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR InfPath,
  [in]            DWORD   Flags,
  [out, optional] PBOOL   NeedReboot
);

参数

[in, optional] hwndParent

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

[in] InfPath

指向以 NULL 结尾的字符串的指针，该字符串为 驱动程序包提供 INF 文件的完全限定路径。

[in] Flags

DWORD 类型的值，指定零或一个或多个标志的组合，如此处所述 (标志 通常设置为零) 。

如果 Flags 为零， 则 DiInstallDriver 仅当驱动程序与设备上当前安装的驱动程序更匹配时，才会在设备上安装指定的驱动程序。 有关 Windows 如何为设备选择驱动程序的信息，请参阅 Windows 如何选择驱动程序。

如果 Flags 包含 DIIRFLAG_FORCE_INF，DiInstallDriver 会在匹配的设备上安装指定的驱动程序，无论驱动程序是否比设备上当前安装的驱动程序更适合设备。 如果还指定了DIIRFLAG_INSTALL_AS_SET，则忽略DIIRFLAG_FORCE_INF。

谨慎 强制安装驱动程序可能会导致将更兼容的或较新的驱动程序替换为兼容性较差或较旧的驱动程序。
 

如果 Flags 包括 Windows 10 版本 1709 及更高版本) 上支持的DIIRFLAG_INSTALL_AS_SET (，InfPath 应指定一个目录，而不是 INF 文件的完全限定路径，DiInstallDriver 将以特殊行为在该目录中安装所有 INF 文件。 所有 驱动程序包 都将暂存到 驱动程序存储中 ，但尚未在设备上安装。 下次关闭系统时，这些驱动程序包将可用于在设备上安装，并且这些驱动程序包将安装在最适合的任何设备上，以便设备在下一次启动系统时准备就绪。

[out, optional] NeedReboot

指向 BOOL 类型的指针， DiInstallDriver 设置该值指示是否需要重启系统才能完成安装。 此参数是可选的，可以为 NULL。 如果提供了 参数，并且需要重启系统才能完成安装， 则 DiInstallDriver 会将值设置为 TRUE。 在这种情况下，调用方必须提示用户重启系统。 如果提供了此参数，并且不需要系统重启即可完成安装， 则 DiInstallDriver 会将该值设置为 FALSE。 如果 参数为 NULL 并且需要重启系统才能完成安装， 则 DiInstallDriver 将显示系统重启对话框。 有关此参数的详细信息，请参阅以下 “备注” 部分。

返回值

如果函数在驱动程序存储区中成功预安装了指定的驱动程序包，DiInstallDriver 将返回 TRUE。 如果函数在系统中的一个或多个设备上成功安装了驱动程序，DiInstallDriver 也会返回 TRUE。 如果驱动程序包未在驱动程序存储中成功安装， DiInstallDriver 将返回 FALSE ，并且可以通过调用 GetLastError 来检索记录的错误。 GetLastError 可能返回的一些更常见的错误值如下所示：

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

注解

DiInstallDriver 执行以下操作：

  1. 在驱动程序存储中预安装驱动程序包。 如果驱动程序存储中已预安装了同一驱动程序包的实例， DiInstallDriver 首先删除该实例，然后将该驱动程序包的新实例添加到驱动程序存储。
  2. 枚举系统中存在的设备。
  3. 如果 Flags 等于零，则仅当指定的驱动程序与设备上当前安装的驱动程序更匹配时，才会在设备上安装驱动程序。
  4. 如果 Flags 等于 DIIRFLAG_FORCE_INF，则无论 驱动程序包 是否比设备上当前安装的驱动程序更匹配设备，都会在设备上安装驱动程序。
通常，安装应用程序应将 NeedReboot 设置为 NULL ，以指示 DiInstallDriver 在需要重启才能完成安装时提示用户重启系统。 应用程序应仅在以下情况下提供 NeedReboot 指针：
  • 应用程序必须多次调用 DiInstallDriver 才能完成安装。 在这种情况下，应用程序应记录对 DiInstallDriver 的任何调用是否返回 TRUENeedReboot 值，如果是，则提示用户在最终调用 DiInstallDriver 返回后重启系统。
  • 应用程序必须执行除调用 DiInstallDriver 以外的必需操作，然后系统重启。 如果需要重启系统，应用程序应完成所需的操作，然后提示用户重启系统。
  • 应用程序是类安装程序，在这种情况下，类安装程序应在设备的 SP_DEVINSTALL_PARAMS 结构的 Flags 成员中设置DI_NEEDREBOOT标志。
若要在所选设备上安装所选驱动程序，请调用 DiInstallDevice。 有关详细信息，请参阅 简化驱动程序安装的安装程序API 函数。

注意

newdev.h 标头将 DiInstallDriver 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

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

另请参阅

DiInstallDevice