UpdateDriverForPlugAndPlayDevicesA 函数 (newdev.h)

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

语法

BOOL UpdateDriverForPlugAndPlayDevicesA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR HardwareId,
  [in]            LPCSTR 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 值的设备。 有关详细信息,请参阅 编写设备安装应用程序

UpdateDriverForPlugAndPlayDevicesIRP_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