RegEnumKeyExA 函数 (winreg.h)

项目
03/11/2023

枚举指定打开的注册表项的子项。函数在每次调用时检索有关一个子项的信息。

语法

LSTATUS RegEnumKeyExA(
  [in]                HKEY      hKey,
  [in]                DWORD     dwIndex,
  [out]               LPSTR     lpName,
  [in, out]           LPDWORD   lpcchName,
                      LPDWORD   lpReserved,
  [in, out]           LPSTR     lpClass,
  [in, out, optional] LPDWORD   lpcchClass,
  [out, optional]     PFILETIME lpftLastWriteTime
);

参数

[in] hKey

打开的注册表项的句柄。必须已使用KEY_ENUMERATE_SUB_KEYS访问权限打开密钥。有关详细信息，请参阅注册表项安全和访问权限。

此句柄由 RegCreateKeyEx、 RegCreateKeyTransacted、 RegOpenKeyEx 或 RegOpenKeyTransacted 函数返回。也可以是以下预定义键之一：

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

要检索的子项的索引。首次调用 RegEnumKeyEx 函数时，此参数应为零，然后针对后续调用递增。

由于子项未排序，因此任何新子项都将具有任意索引。这意味着函数可以按任意顺序返回子项。

[out] lpName

指向接收子项名称（包括终止 null 字符）的缓冲区的指针。函数仅将子项的名称（而不是完整键层次结构）复制到缓冲区。

如果函数失败，则不会将任何信息复制到此缓冲区。

有关详细信息，请参阅注册表元素大小限制。

[in, out] lpcchName

指向变量的指针，该变量指定 由 lpName 参数指定的缓冲区的大小（以字符为单位）。此大小应包含终止 null 字符。如果函数成功， 则 lpcchName 指向的变量包含缓冲区中存储的字符数，不包括终止 null 字符。

若要确定所需的缓冲区大小，请使用 RegQueryInfoKey 函数确定 由 hKey 参数标识的键的最大子项的大小。

lpReserved

此参数是保留的，必须为 NULL。

[in, out] lpClass

指向接收枚举子项的用户定义类的缓冲区的指针。此参数可以为 NULL。

[in, out, optional] lpcchClass

指向变量的指针，该变量指定 由 lpClass 参数指定的缓冲区的大小（以字符为单位）。大小应包括终止 null 字符。如果函数成功， 则 lpcchClass 包含缓冲区中存储的字符数，不包括终止 null 字符。仅当 lpClass 为 NULL 时，此参数才能为 NULL。

[out, optional] lpftLastWriteTime

指向 FILETIME 结构的指针，该结构接收上次写入枚举子项的时间。此参数可以为 NULL。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值为系统错误代码。如果没有其他可用的子项，函数将返回ERROR_NO_MORE_ITEMS。

如果 lpName 缓冲区太小而无法接收密钥的名称，则函数将返回ERROR_MORE_DATA。

注解

若要枚举子项，应用程序最初应调用 RegEnumKeyEx 函数，并将 dwIndex 参数设置为零。然后，应用程序应递增 dwIndex 参数并调用 RegEnumKeyEx ，直到没有更多的子项 (这意味着函数返回ERROR_NO_MORE_ITEMS) 。

应用程序还可以在首次调用函数时将 dwIndex 设置为最后一个子项的索引，并递减索引，直到枚举索引为 0 的子项。若要检索最后一个子项的索引，请使用 RegQueryInfoKey 函数。

当应用程序使用 RegEnumKeyEx 函数时，它不应调用任何可能会更改所枚举密钥的注册函数。

请注意，将重定向访问某些注册表项的操作。有关详细信息，请参阅注册表虚拟化和注册表中的 32 位和 64 位应用程序数据。

注意

在旧版 Windows 上，此 API 也由 kernel32.dll 公开。

示例

有关示例，请参阅枚举注册表子项。

注意

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

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winreg.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll