setupDiInstallDevice 函数 (setupapi.h)

  • 项目

SetupDiInstallDevice 函数是DIF_INSTALLDEVICE安装请求的默认处理程序。

语法

WINSETUPAPI BOOL SetupDiInstallDevice(
  [in]      HDEVINFO         DeviceInfoSet,
  [in, out] PSP_DEVINFO_DATA DeviceInfoData
);

参数

[in] DeviceInfoSet

本地系统 的设备信息集 的句柄，其中包含表示要安装的设备的设备信息元素。

[in, out] DeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，该结构指定 DeviceInfoSet 中的设备信息元素。 这是 IN-OUT 参数，因为 DeviceInfoData。返回时，DevInst 可能会使用新的句柄值进行更新。

返回值

如果成功，函数将返回 TRUE 。 否则，它将返回 FALSE ，并且可以通过调用 GetLastError 来检索记录的错误。

注解

SetupDiInstallDevice 从 INF 文件安装驱动程序。 SetupAPI 对“驱动程序”的定义实际上是一个“驱动程序节点”。因此，当此函数安装驱动程序时，它还会安装以下列表中的项：

  • 服务 (设备的) 。
  • 驱动程序文件。
  • 如果有任何) ，特定于设备的辅助安装程序 (。
  • 属性页提供程序 (任何) 。
  • 如果有任何) ，控制面板小程序 (。
此函数还会注册任何所需的设备接口。

成功安装包括但不限于以下步骤：

  • 在注册表中创建 驱动程序密钥 ， (写入相应的条目，例如 InfPath 和 ProviderName) 。
  • 找到并处理设备的 INF DDInstall 部分 。 部分可能特定于 OS/体系结构。 DDInstall 部分的 AddReg 和 DelReg 条目定向到设备的软件密钥。 找到并处理 DDInstall。HW 部分，其 AddReg 和 DelReg 条目定向到设备 的硬件密钥。 找到并处理 INF DDInstall.LogConfigOverride 部分（如果存在），为设备提供 替代配置 。 找到并处理 INF DDInstall.Services 部分 以添加设备 (的服务，并可能删除不再需要) 的任何旧服务。
  • 将 INF 文件复制到系统 INF 目录。
  • 可能根据设备安装参数中的标志设置执行其他文件操作。

    如果DI_NOFILECOPY标志和DI_NOVCP标志 是明确的，请执行 DDInstall 节中指定的任何文件操作。 如果设置了 DI_NOVCP 标志，则对任何文件操作进行排队。

    如果设置了DI_NOFILECOPY标志，请不要复制文件。 例如，如果已为此设备安装执行 了DIF_INSTALLDEVICEFILES 操作，则可以设置此标志。

  • 加载设备的驱动程序。 这包括函数驱动程序以及任何上限或下限筛选器驱动程序。
  • 调用驱动程序的 AddDevice 例程。
  • 通过 (IRP) 发送IRP_MN_START_DEVICE I/O 请求数据包来启动设备。
如果在SP_DEVINSTALL_PARAMS结构中设置了DI_NEEDRESTART、DI_NEEDREBOOT或DI_DONOTCALLCONFIGMG标志，Windows 不会启动 设备 。

处理DIF_INSTALLDEVICE请求时，类安装程序应返回 ERROR_DI_DO_DEFAULT 或调用此函数。 此函数执行许多设备安装任务，该任务列表可能会在将来的版本中扩展。 如果类安装程序在不调用此函数的情况下执行设备安装，则类安装程序可能无法在操作系统的未来版本上正常工作。

如果 Windows 找不到设备的 INF 文件，它将发送DIF_INSTALLDEVICE以尝试安装 null 驱动程序。 仅当设备支持原始模式或是 IoReportDetectedDevice) 报告的非 PnP 设备 (时，SetupDiInstallDevice 才会安装 null 驱动程序。 有关详细信息，请参阅 DIF_INSTALLDEVICE。

如果在 SP_DEVINSTALL_PARAMS 结构中 设置了DI_FLAGSEX_SETFAILEDINSTALL标志， 则 SetupDiInstallDevice 只会在设备的 ConfigFlags 注册表值中设置 FAILEDINSTALL 标志。

注意 只有 类安装程序 应调用 SetupDiInstallDevice ，并且仅在类安装程序必须在 SetupDiInstallDevice 完成默认设备安装操作后执行设备安装操作的情况下调用。 在这种情况下，当安装程序处理DIF_INSTALLDEVICE请求时，类安装程序必须直接调用 SetupDiInstallDevice 。 有关调用默认处理程序的详细信息，请参阅 调用默认 DIF 代码处理程序。
 
SetupDiInstallDevice 的调用方必须是 Administrators 组的成员。

要求

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

另请参阅

DIF_INSTALLDEVICE

SetupDiCallClassInstaller

SetupDiInstallDriverFiles