SetupDiCreateDevRegKeyA 函数 (setupapi.h)

项目
08/26/2023

SetupDiCreateDevRegKey 函数为特定于设备的配置信息创建注册表项，并返回该项的句柄。

语法

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

参数

[in] DeviceInfoSet

设备信息集的句柄，其中包含表示要为其创建注册表项的设备的设备信息元素。

[in] DeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，该结构指定 DeviceInfoSet 中的设备信息元素。

[in] Scope

要创建的注册表项的范围。范围确定信息的存储位置。创建的密钥可以是全局密钥，也可以是特定于硬件配置文件的。可以是以下其中一个值：

DICS_FLAG_GLOBAL

创建密钥以存储全局配置信息。此信息不特定于特定的硬件配置文件。在基于 NT 的操作系统上，这会创建一个根位于 HKEY_LOCAL_MACHINE 的密钥。打开的确切键取决于 KeyType 参数的值。

DICS_FLAG_CONFIGSPECIFIC

创建密钥以存储特定于硬件配置文件的配置信息。此密钥植根于硬件配置文件特定的分支之一，而不是 HKEY_LOCAL_MACHINE。

[in] HwProfile

如果 HwProfileFlags 设置为 SPDICS_FLAG_CONFIGSPECIFIC，则为其创建密钥的硬件配置文件。如果 HwProfile 为 0，则创建当前硬件配置文件的密钥。如果 SPDICS_FLAG_GLOBAL HwProfileFlags ，则忽略 HwProfile 。

[in] KeyType

要创建的注册表存储密钥的类型。可以是以下其中一个值：

DIREG_DEV

为设备创建硬件密钥。

DIREG_DRV

为设备创建软件密钥。

[in, optional] InfHandle

打开的 INF 文件的句柄，该文件包含要为新创建的密钥执行的 INF DDInstall 节。此参数是可选的，可以为 NULL。如果指定此参数，还必须指定 InfSectionName 。

[in, optional] InfSectionName

InfHandle 指定的 INF 文件中的 INF DDInstall 节的名称。此部分针对新创建的密钥执行。此参数是可选的，可以为 NULL。如果指定此参数，则还必须指定 InfHandle 。

返回值

如果 SetupDiCreateDevRegKey 成功，该函数将返回指定注册表项的句柄，可在其中存储和检索特定于设备的配置数据。如果 SetupDiCreateDevRegKey 失败，该函数将返回INVALID_HANDLE_VALUE。调用 GetLastError 可获取扩展错误信息。

注解

SetupDiCreateDevRegKey 的调用方必须是 Administrators 组的成员。

通过调用 RegCloseKey 关闭从 SetupDiCreateDevRegKey 返回的句柄。

如果指定的键已存在， SetupDiCreateDevRegKey 将返回该键的句柄。否则， SetupDiCreateDevRegKey 将创建指定的键，并返回新密钥的句柄。对于 Windows Server 2003 及更高版本的 Windows，键句柄仅具有KEY_READ和KEY_WRITE访问权限。对于以前的 Windows 版本，此句柄具有KEY_ALL_ACCESS访问权限。

在调用 SetupDiCreateDevRegKey 之前，必须注册指定的设备实例。但请注意，操作系统会自动注册 PnP 设备实例。有关如何注册非 PnP 设备实例的信息，请参阅 SetupDiRegisterDeviceInfo。

对于使用布局文件 (INF 版本部分) 的 LayoutFile 条目指定的安装，必须在调用 SetupDiCreateDevRegKey 之前，通过调用 SetupOpenAppendInfFile (中所述的 Microsoft Windows SDK setupOpenAppendInfFile) 来打开布局文件。

如果提供的设备信息集包含远程系统的设备信息元素，并且还指定了 InfHandle 和 InfSectionName ，则创建请求将失败，并且对 GetLastError 的后续调用将返回ERROR_REMOTE_REQUEST_UNSUPPORTED。

注意

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

要求

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