RegEnumKeyA 函数 (winreg.h)
枚举指定打开的注册表项的子项。 每次调用函数时,函数都会检索一个子项的名称。
语法
LSTATUS RegEnumKeyA(
[in] HKEY hKey,
[in] DWORD dwIndex,
[out] LPSTR lpName,
[in] DWORD cchName
);
参数
[in] hKey
打开的注册表项的句柄。 密钥必须已使用KEY_ENUMERATE_SUB_KEYS访问权限打开。 有关详细信息,请参阅 注册表项安全和访问权限。
此句柄由 RegCreateKeyEx、 RegCreateKeyTransacted、 RegOpenKeyEx 或 RegOpenKeyTransacted 函数返回。 也可以是以下 预定义键之一:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_USERS
[in] dwIndex
要检索的 hKey 子项的索引。 对于第一次调用 RegEnumKey 函数,此值应为零,然后针对后续调用递增。
由于子项未排序,因此任何新子项都将具有任意索引。 这意味着该函数可以按任意顺序返回子项。
[out] lpName
指向接收子项名称(包括终止 null 字符)的缓冲区的指针。 此函数仅将子项的名称(而不是完整键层次结构)复制到缓冲区。
有关详细信息,请参阅 注册表元素大小限制。
[in] cchName
lpName 参数指向的缓冲区的大小(以 TCHAR 为单位)。 若要确定所需的缓冲区大小,请使用 RegQueryInfoKey 函数确定 由 hKey 参数标识的键的最大子项的大小。
返回值
如果函数成功,则返回值为 ERROR_SUCCESS。
如果函数失败,则返回值为 系统错误代码。 如果没有其他可用子项,该函数将返回ERROR_NO_MORE_ITEMS。
如果 lpName 缓冲区太小而无法接收密钥的名称,则函数将返回ERROR_MORE_DATA。
注解
若要枚举子项,应用程序最初应调用 RegEnumKey 函数,并将 dwIndex 参数设置为零。 然后,应用程序应递增 dwIndex 参数并调用 RegEnumKey 函数,直到没有更多子项 (这意味着函数返回ERROR_NO_MORE_ITEMS) 。
应用程序还可以在首次调用函数时将 dwIndex 设置为最后一个键的索引,并递减索引,直到枚举索引为 0 的子项。 若要检索最后一个子项的索引,请使用 RegQueryInfoKey。
当应用程序使用 RegEnumKey 函数时,它不应调用任何可能会更改正在查询的密钥的注册函数。
注意
winreg.h 标头将 RegEnumKey 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
目标平台 | Windows |
标头 | winreg.h (包括 Windows.h) |
Library | Advapi32.lib |
DLL | Advapi32.dll |