SP_DEVINSTALL_PARAMS_A 结构 (setupapi.h)

  • 项目

SP_DEVINSTALL_PARAMS结构包含与特定设备信息元素关联的设备安装参数，或与设备信息集全局关联的设备安装参数。

语法

typedef struct _SP_DEVINSTALL_PARAMS_A {
  DWORD             cbSize;
  DWORD             Flags;
  DWORD             FlagsEx;
  HWND              hwndParent;
  PSP_FILE_CALLBACK InstallMsgHandler;
  PVOID             InstallMsgHandlerContext;
  HSPFILEQ          FileQueue;
  ULONG_PTR         ClassInstallReserved;
  DWORD             Reserved;
  CHAR              DriverPath[MAX_PATH];
} SP_DEVINSTALL_PARAMS_A, *PSP_DEVINSTALL_PARAMS_A;

成员

cbSize

SP_DEVINSTALL_PARAMS结构的大小（以字节为单位）。

Flags

控制安装和用户界面操作的标志。 某些标志可以在发送设备安装请求之前设置，而其他标志是在处理某些请求期间自动设置的。 标志 可以是以下值的组合。

标志值按组列出：设备 安装应用程序和 安装程序可写、只读 (仅由 OS) 、保留和过时设置。 第一个组列出了可写的标志：

DI_CLASSINSTALLPARAMS

设置为使用类安装参数。 SetupDiSetClassInstallParams 在调用方指定参数时设置此标志，并在调用方指定 NULL 参数指针时清除该标志。

DI_COMPAT_FROM_CLASS

设置为强制 SetupDiBuildDriverInfoList 从其类驱动程序列表而不是 INF 文件生成设备的兼容驱动程序列表。

DI_DRIVERPAGE_ADDED

如果安装程序提供替换系统提供的驱动程序属性页的页面，则由类安装程序或辅助安装程序设置。 如果设置了此标志，则操作系统不会显示系统提供的驱动程序页。

DI_DONOTCALLCONFIGMG

设置是否不应调用配置管理器，以便在执行某些设备安装功能期间删除或恢复设备， (例如 SetupDiInstallDevice) 。

如果设置了此标志，则设备安装应用程序、类安装程序和辅助安装程序不得调用以下函数：

CM_Reenumerate_DevNodeCM_Reenumerate_DevNode_ExCM_Query_And_Remove_SubTree CM_Query_And_Remove_SubTree_Ex CM_Setup_DevNodeCM_Setup_DevNode_ExCM_Set_HW_Prof_FlagsCM_Set_HW_Prof_Flags_Ex CM_Set_HW_Prof_Flags_ExCM_Enable_DevNode CM_Enable_DevNode_ExCM_Disable_DevNodeCM_Disable_DevNode_Ex

DI_ENUMSINGLEINF

设置安装程序和其他 设备安装组件 是否应仅搜索由 SP_DEVINSTALL_PARAMS 指定的 INF 文件。DriverPath。 如果设置了此标志， DriverPath 将包含单个 INF 文件的路径，而不是目录的路径。

DI_INF_IS_SORTED

设置为指示“选择设备”页应按驱动程序在 INF 文件中出现的顺序列出驱动程序，而不是按字母顺序对其进行排序。

DI_INSTALLDISABLED

设置默认情况下是否应以禁用状态安装设备。 若要进行识别，必须在 Windows 为 DIF_INSTALLDEVICE 请求调用默认处理程序之前设置此标志。

DI_NEEDREBOOT

对于基于 NT 的操作系统，如果设备要求在设备安装或设备状态更改后重启计算机，则会设置此标志。 如果安装程序确定需要重启，类安装程序或辅助安装程序可以在设备安装期间随时设置此标志。

DI_NEEDRESTART

与 DI_NEEDREBOOT 相同。

DI_NOBROWSE

设置为在用户选择 OEM 磁盘路径时禁用浏览。 设备安装应用程序设置此标志以将用户限制为仅从安装媒体位置进行安装。

DI_NODI_DEFAULTACTION

如果类安装程序返回ERR_DI_DO_DEFAULT或没有类安装程序， 则设置 SetupDiCallClassInstaller 不应执行任何默认操作。

DI_NOFILECOPY

设置设备安装应用程序和组件（如 SetupDiInstallDevice）是否应跳过文件复制。

DI_NOVCP

设置为禁用创建新复制队列。 在 SP_DEVINSTALL_PARAMS 中使用调用方提供的复制队列。FileQueue。

DI_NOWRITE_IDS

设置为阻止 SetupDiInstallDevice 将 INF 指定的 硬件 ID 和 兼容 ID 写入设备节点的设备属性， (devnode) 。 应仅为根枚举设备设置此标志。

此标志替代 DI_FLAGSEX_ALWAYSWRITEIDS 标志。

DI_PROPERTIES_CHANGE

由 设备管理器更改设备属性时设置，这需要更新安装程序的用户界面。

DI_QUIETINSTALL

设置设备安装程序功能是否必须为无提示功能，并尽可能使用默认选项。 如果设置了此标志，类安装程序和辅助安装程序不得显示任何 UI。

DI_RESOURCEPAGE_ADDED

如果安装程序提供替换系统提供的资源属性页，则由类安装程序或辅助安装程序设置。 如果设置了此标志，则操作系统不会显示系统提供的资源页。

DI_SHOWOEM

设置为允许对 OEM 磁盘的支持。 如果设置了此标志，则操作系统在“选择设备”页上显示“具有磁盘”按钮。 默认情况下，此标志在系统提供的向导中设置。

DI_USECI_SELECTSTRINGS

设置类安装程序或辅助安装程序是否提供了应在 SetupDiSelectDevice 期间使用的字符串。

以下标志是只读 (仅由 OS) 设置：

DI_DIDCLASS

如果 SetupDiBuildDriverInfoList 已为此类设备生成驱动程序列表，请设置 。 如果已生成此列表，则包含所有驱动程序信息，并且始终设置此标志。 SetupDiDestroyDriverInfoList 在删除类的驱动程序列表时清除此标志。

此标志为只读。 只有操作系统设置此标志。

DI_DIDCOMPAT

如果 SetupDiBuildDriverInfoList 已为此设备生成兼容驱动程序列表，请设置 。 如果已生成此列表，则包含所有驱动程序信息，并且始终设置此标志。 SetupDiDestroyDriverInfoList 在删除兼容的驱动程序列表时清除此标志。

此标志仅在与特定设备信息元素关联的设备安装参数中设置，而不是在设备信息集整体的参数中设置。

此标志为只读。 只有操作系统设置此标志。

DI_MULTMFGS

如果设备安装类的驱动程序列表包含由多个制造商提供的驱动程序，则由 SetupDiBuildDriverInfoList 设置。

此标志为只读。 只有操作系统设置此标志。

保留以下标志：

DI_AUTOASSIGNRES

DI_DISABLED

DI_FORCECOPY

DI_GENERALPAGE_ADDED

DI_OVERRIDE_INFFLAGS

DI_SHOWALL

DI_SHOWCLASS

DI_SHOWCOMPAT

以下标志已过时：

DI_NOSELECTICONS

DI_PROPS_NOCHANGEUSAGE

FlagsEx

用于控制安装和用户界面操作的其他标志。 某些标志可以在调用设备安装程序函数之前设置，而其他标志是在处理某些函数期间自动设置的。 FlagsEx 可以是以下值的组合。

标志值按组列出：设备安装应用程序和安装程序可写、只读 (仅由 OS) 、保留和过时设置。

第一个组列出了可写的标志：

DI_FLAGSEX_ALLOWEXCLUDEDDRVS

如果已设置，请包含标记为“从选择中排除”的驱动程序。

例如，如果设置了此标志， SetupDiSelectDevice 将显示具有“从选择中排除”状态的驱动程序， SetupDiBuildDriverInfoList 在请求的驱动程序列表中包括“从选择中排除”驱动程序。

如果驱动程序在 INF 文件中标记为 ExcludeFromSelect ，或者是整个安装类在类安装程序 INF 中标记为 NoInstallClass 或 NoUseClass 的设备驱动程序，则驱动程序为“从选择中排除”。 PnP 设备的驱动程序通常为“从选择中排除”;不应手动安装 PnP 设备。 若要为 PnP 设备生成驱动程序文件列表， SetupDiBuildDriverInfoList 的调用方必须设置此标志。

DI_FLAGSEX_ALWAYSWRITEIDS

如果已设置且DI_NOWRITE_IDS标志明确，请始终将硬件和兼容 ID 写入开发节点的设备属性。 应仅为根枚举设备设置此标志。

DI_FLAGSEX_APPENDDRIVERLIST

如果已设置， SetupDiBuildDriverInfoList 会将新的驱动程序列表追加到现有列表。 搜索多个位置时，此标志相关。

DI_FLAGSEX_DRIVERLIST_FROM_URL

如果已设置，则从 INF 生成驱动程序列表， (从 SP_DEVINSTALL_PARAMS 中指定的 URL 检索到的) 。DriverPath。 如果 DriverPath 是空字符串，请使用 Windows 更新 网站。

目前，操作系统不支持 URL。 使用此标志指示 SetupDiBuildDriverInfoList 搜索Windows 更新网站。

如果设置了DI_QUIETINSTALL，请不要设置此标志。

DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS

如果已设置，则不要在生成驱动程序列表时包括旧的 Internet 驱动程序。 每当为设备生成潜在驱动程序列表时，都应设置此标志。 如果只是获取当前为设备安装的驱动程序列表，则可以清除此标志。

DI_FLAGSEX_FILTERCLASSES

如果设置，SetupDiBuildClassInfoList 将为类包含筛选器检查。 这意味着，如果设备类被标记为 NoInstallClass，则不会包含在类列表中。

DI_FLAGSEX_FILTERSIMILARDRIVERS

(Windows XP 及更高版本。) 如果设置， 则 SetupDiBuildDriverInfoList 在生成类驱动程序列表时包括“类似”驱动程序。 “相似”驱动程序是 INF 文件中硬件 ID 或兼容 ID 之一部分 (或完全) 与硬件的其中一个硬件 ID 或兼容 ID 匹配的驱动程序。

DI_FLAGSEX_FINISHINSTALL_ACTION

(Windows Vista 及更高版本。) 有关详细信息 ，请参阅将设备标记为具有要执行的 Finish-Install 操作 。

DI_FLAGSEX_INET_DRIVER

如果设置，则驱动程序是从 Internet 获取的。 Windows 不会使用设备的 INF 来安装将来的设备，因为 Windows 无法保证它可以再次从 Internet 检索驱动程序文件。

DI_FLAGSEX_INSTALLEDDRIVER

(Windows XP 及更高版本。) 如果设置， SetupDiBuildDriverInfoList 在创建类驱动程序或设备兼容驱动程序的列表时仅包含当前安装的驱动程序。

DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE

(Windows XP 及更高版本。) 如果设置，在创建类驱动程序列表时， SetupDiBuildDriverInfoList 将不会合并来自同一 INF 且具有相同驱动程序说明和排名的驱动程序列表中的节点。

DI_FLAGSEX_NO_DRVREG_MODIFY

请勿处理设备的硬件和软件的 AddReg 和 DelReg 条目， (驱动程序) 密钥。 即 INF 文件 DDInstall 和 DDInstall 中的 AddReg 和 DelReg 条目。HW 部分。

DI_FLAGSEX_POWERPAGE_ADDED

如果设置，安装程序会为电源属性对话框添加自己的页面。 操作系统不会显示系统提供的电源属性页。 仅当设备支持电源管理时，此标志才相关。

DI_FLAGSEX_PROPCHANGE_PENDING

如果设置，则用户对一个或多个设备属性表进行了更改。 属性页提供程序通常设置此标志。

当用户关闭设备属性表时，设备管理器检查DI_FLAGSEX_PROPCHANGE_PENDING标志。 如果已设置，设备管理器清除此标志，设置DI_PROPERTIES_CHANGE标志，并向安装程序发送DIF_PROPERTYCHANGE请求，以通知他们某些内容已更改。

DI_FLAGSEX_RECURSIVESEARCH

(Windows Vista 及更高版本。) 如果设置，当 SetupDiBuildDriverInfoList 在 DriverPath 值中指定的路径中搜索 INF 时，搜索将是递归的。

DI_FLAGSEX_SEARCH_PUBLISHED_INFS

(Windows Vista 及更高版本。) 如果设置，当 使用 SetupDiBuildDriverInfoList 搜索未指定 INF 路径或搜索路径的 INF 时，这会将搜索限制为仅搜索已导入驱动程序存储的 INF。

DI_FLAGSEX_SETFAILEDINSTALL

如果安装失败，则设置 。 如果设置了此标志， 则 SetupDiInstallDevice 函数只会在设备的 ConfigFlags 注册表值中设置 FAILEDINSTALL 标志。 如果设置了DI_FLAGSEX_SETFAILEDINSTALL，辅助安装程序必须返回NO_ERROR以响应DIF_INSTALLDEVICE，而类安装程序必须返回NO_ERROR或ERROR_DI_DO_DEFAULT。

DI_FLAGSEX_USECLASSFORCOMPAT

生成兼容驱动程序列表时，筛选设备的安装程序类上的 INF 文件。 如果设备的安装类已知，则设置此标志可缩短在搜索未预编译的 INF 文件时生成兼容驱动程序列表所需的时间。 如果设置了DI_COMPAT_FROM_CLASS，则忽略此标志。

以下标志为只读;只有操作系统设置以下标志：

DI_FLAGSEX_CI_FAILED

如果类安装程序无法加载或启动，则由操作系统设置。 此标志为只读。

DI_FLAGSEX_DIDCOMPATINFO

Windows 已生成与设备兼容的 驱动程序节点 列表。 此标志为只读。

DI_FLAGSEX_DIDINFOLIST

Windows 已生成驱动程序节点列表，其中包括指定安装程序类的 INF 文件中列出的所有驱动程序。 如果由于 HDEVINFO 集或设备没有关联的类而指定的安装类为 NULL ，则该列表包括所有可用 INF 文件中的所有驱动程序节点。 此标志为只读。

DI_FLAGSEX_IN_SYSTEM_SETUP

如果设置，则会在初始系统设置期间进行安装。 此标志为只读。

以下标志是保留的，不应使用：

DI_FLAGSEX_ALTPLATFORM_DRVSEARCH

DI_FLAGSEX_BACKUPONREPLACE

DI_FLAGSEX_DEVICECHANGE

DI_FLAGSEX_OLDINF_IN_CLASSLIST

DI_FLAGSEX_PREINSTALLBACKUP

DI_FLAGSEX_RESTART_DEVICE_ONLY

DI_FLAGSEX_USEOLDINFSEARCH

以下标志已过时：

DI_FLAGSEX_AUTOSELECTRANK0

DI_FLAGSEX_NOUIONQUERYREMOVE

hwndParent

将拥有与此设备相关的用户界面对话框的窗口句柄。

InstallMsgHandler

用于在文件复制期间处理事件的回调。 例如，安装程序可以使用回调在提交文件队列时执行特殊处理。

InstallMsgHandlerContext

InstallMsgHandler 回调使用的专用数据。

FileQueue

调用方提供的文件队列的句柄，其中的文件操作应排队但不提交。

如果将文件队列与 setupDiSetDeviceInstallParams) (设备信息集相关联，则必须在删除设备信息集之前取消该队列与设备信息集的关联。 如果未能取消关联文件队列，则 Windows 无法递减其在设备信息集上的引用计数，并且无法释放内存。

仅当设置了 DI_NOVCP 标志时，才使用此队列，指示应将文件操作排入队列但未提交。

ClassInstallReserved

类安装程序数据的指针。 共同安装程序不得使用此字段。

Reserved

保留。 仅限内部使用。

DriverPath[MAX_PATH]

SetupDiBuildDriverInfoList 函数使用此路径。

注解

注意

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

要求

要求 值
Header setupapi.h (包括 Setupapi.h)

另请参阅

SetupDiBuildClassInfoList

SetupDiBuildDriverInfoList

SetupDiCallClassInstaller

SetupDiGetDeviceInstallParams

SetupDiInstallDevice

SetupDiSelectDevice

SetupDiSetDeviceInstallParams