UpdateDriverForPlugAndPlayDevicesW 函数 (newdev.h)

  • 项目

在给定 INF 文件和 硬件 ID 的情况下， UpdateDriverForPlugAndPlayDevices 函数会为与硬件 ID 匹配的设备安装更新的驱动程序。

语法

BOOL UpdateDriverForPlugAndPlayDevicesW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR HardwareId,
  [in]            LPCWSTR FullInfPath,
  [in]            DWORD   InstallFlags,
  [out, optional] PBOOL   bRebootRequired
);

参数

[in, optional] hwndParent

顶级窗口的句柄，用于与安装设备相关的任何 UI。

[in] HardwareId

指向以 NULL 结尾的字符串的指针，该字符串提供硬件标识符以匹配计算机上的现有设备。 以 NULL 结尾的硬件标识符的最大长度MAX_DEVICE_ID_LEN。 有关硬件标识符的详细信息，请参阅 设备标识字符串。

[in] FullInfPath

指向以 NULL 结尾的字符串的指针，该字符串提供 INF 文件的完整路径文件名。 这些文件应位于分发媒体上或供应商创建的目录中，而不是在系统位置（如 %SystemRoot%\inf）中。 如果安装成功，UpdateDriverForPlugAndPlayDevices 会将驱动程序文件复制到相应的系统位置。

[in] InstallFlags

通过使用 OR 合并以下零个或多个位标志而创建的调用方提供的值：

INSTALLFLAG_FORCE

如果设置了此标志，并且函数找到与 HardwareId 值匹配的设备，则无论计算机上是否已存在更好的驱动程序，该函数都为设备安装新的驱动程序。

重要 请谨慎使用此标志。 如果用户在更新的驱动程序可用后运行供应商的应用程序，设置此标志可能会导致较旧的驱动程序安装在较新的驱动程序上。
 

INSTALLFLAG_READONLY

如果设置了此标志，该函数将不会复制、重命名或删除任何安装文件。 应将此标志的使用限制为限制或无法访问文件的环境，例如“嵌入式”操作系统。

INSTALLFLAG_NONINTERACTIVE

如果设置了此标志，当检测到任何显示 UI 的尝试时，函数将返回 FALSE 。 仅当将从组件 (（例如无法显示 UI 的服务) ）调用函数时，才设置此标志。

注意 如果设置了此标志并尝试显示 UI，则设备可能处于不确定状态。
 
InstallFlags 参数通常为零。

[out, optional] bRebootRequired

指向 BOOL 类型的变量的指针，该变量指示是否需要重启以及谁应提示重启。 此指针是可选的，可以为 NULL。

如果指针为 NULL，UpdateDriverForPlugAndPlayDevices 会在安装驱动程序后提示重启（如有必要）。 如果提供了指针，则函数返回一个 BOOLEAN 值，如果系统应重启，则返回 TRUE 。 然后，调用方负责提示重启。

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

返回值

如果设备已升级到指定的驱动程序，则函数返回 TRUE 。

否则，它将返回 FALSE ，并且可以通过调用 GetLastError 来检索记录的错误。 下表包含 GetLastError 返回的可能错误值。

返回代码 说明
ERROR_FILE_NOT_FOUND
 为 FullInfPath 指定的路径不存在。
ERROR_IN_WOW64
 调用应用程序是尝试在 64 位环境中执行的 32 位应用程序，这是不允许的。
ERROR_INVALID_FLAGS
 为 InstallFlags 指定的值无效。
ERROR_NO_SUCH_DEVINST
 为 HardwareId 指定的值与系统上的任何设备都不匹配。 也就是说，设备未接通电源。
ERROR_NO_MORE_ITEMS
 函数找到了 HardwareId 值的匹配项，但指定的驱动程序不是比当前驱动程序更好的匹配项，并且调用方未指定INSTALLFLAG_FORCE标志。

注解

UpdateDriverForPlugAndPlayDevices 扫描系统上的设备，并尝试为与指定 HardwareId 值匹配的任何设备安装 FullInfPath 指定的驱动程序。

默认行为是仅当指定的驱动程序比当前安装的驱动程序更匹配时，才安装指定的驱动程序，并且指定的驱动程序也比 %SystemRoot%\inf 中的任何驱动程序都更匹配。 有关详细信息，请参阅 Windows 如何选择驱动程序。

UpdateDriverForPlugAndPlayDevices 还可用于确定是否插入具有指定 HardwareId 值的设备。 有关详细信息，请参阅 编写设备安装应用程序。

UpdateDriverForPlugAndPlayDevices 将 IRP_MN_QUERY_REMOVE_DEVICE 请求发送到指定设备、设备的所有子级以及以递归方式属于设备删除关系的所有其他设备。 如果这些设备中的任何一个失败的查询删除请求， UpdateDriverForPlugAndPlayDevices 将设置设备SP_DEVINSTALL_PARAMS结构的 Flags 成员中的 DI_NEEDREBOOT 标志。 有关删除关系的信息，请参阅 IRP_MN_QUERY_DEVICE_RELATIONS 请求。

通常，设备安装应用程序应为 bRebootRequired 提供 NULL。 因此，如有必要，系统将启动重启。 应用程序应仅在以下情况下指定指针值：

  • 应用程序必须多次调用 UpdateDriverForPlugAndPlayDevices 才能完成安装。
  • 如果需要) ，应用程序必须在重启 (之前执行其他操作。
  • 应用程序是类安装程序，如果需要重启，应在 SP_DEVINSTALL_PARAMS 中设置 DI_NEEDREBOOT 。
如果应用程序必须多次调用 UpdateDriverForPlugAndPlayDevices ，它应保存收到的任何 TRUE 重启状态值，然后在返回最终调用后提示重启。

如果函数在 32 位应用程序中返回ERROR_IN_WOW64，则应用程序在 64 位系统上执行，这是不允许的。 有关详细信息，请参阅 在 64 位系统上安装设备。

要求

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