RegEnumValueW 函数 (winreg.h)
枚举指定打开的注册表项的值。 函数在每次调用密钥时复制一个索引值名称和数据块。
语法
LSTATUS RegEnumValueW(
[in] HKEY hKey,
[in] DWORD dwIndex,
[out] LPWSTR lpValueName,
[in, out] LPDWORD lpcchValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD lpcbData
);
参数
[in] hKey
打开的注册表项的句柄。 必须已使用KEY_QUERY_VALUE访问权限打开密钥。 有关详细信息,请参阅 注册表项安全和访问权限。
此句柄由 RegCreateKeyEx、 RegCreateKeyTransacted、 RegOpenKeyEx 或 RegOpenKeyTransacted 函数返回。 也可以是以下 预定义键之一:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_PERFORMANCE_DATA
- HKEY_USERS
[in] dwIndex
要检索的值的索引。 对于第一次调用 RegEnumValue 函数,此参数应为零,然后为后续调用递增。
由于值未排序,因此任何新值都将具有任意索引。 这意味着函数可以按任意顺序返回值。
[out] lpValueName
指向缓冲区的指针,该缓冲区接收以 null 结尾的字符串形式的值的名称。
此缓冲区必须足够大,才能包含终止 null 字符。
有关详细信息,请参阅 注册表元素大小限制。
[in, out] lpcchValueName
指向变量的指针,该变量指定 lpValueName 参数指向的缓冲区的大小(以字符为单位)。 函数返回时,变量接收缓冲区中存储的字符数,不包括终止 null 字符。
注册表值名称限制为 32,767 个字节。 此函数的 ANSI 版本将此参数视为 SHORT 值。 因此,如果指定的值大于 32,767 个字节,则存在溢出,并且函数可能会返回ERROR_MORE_DATA。
lpReserved
此参数是保留的,必须为 NULL。
[out, optional] lpType
指向变量的指针,该变量接收指示存储在指定值中的数据类型的代码。 有关可能的类型代码的列表,请参阅 注册表值类型。 如果不需要类型代码, lpType 参数可以为 NULL 。
[out, optional] lpData
指向接收值条目数据的缓冲区的指针。 如果不需要数据,此参数可以为 NULL 。
如果 lpData 为 NULL 且 ldata 为非 NULL,则该函数会将数据的大小(以字节为单位)存储在 ldata 指向的变量中。 这使应用程序能够确定为数据分配缓冲区的最佳方式。
[in, out, optional] lpcbData
指向变量的指针,该变量指定 lpData 参数指向的缓冲区的大小(以字节为单位)。 函数返回时,变量接收存储在缓冲区中的字节数。
仅当 lpData 为 NULL 时,此参数才能为 NULL。
如果数据具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型,则此大小包括任何终止 null 字符或字符。 有关详细信息,请参阅“备注”。
如果 lpData 指定的缓冲区不够大,无法保存数据,则函数将返回ERROR_MORE_DATA并将所需的缓冲区大小存储在 l ERROR_MORE_DATA指向的变量中。 在这种情况下, lpData 的内容未定义。
返回值
如果函数成功,则返回值为 ERROR_SUCCESS。
如果函数失败,则返回值为 系统错误代码。 如果没有其他可用值,函数将返回ERROR_NO_MORE_ITEMS。
如果 lpData 缓冲区太小而无法接收值,则函数将返回ERROR_MORE_DATA。
注解
若要枚举值,应用程序最初应调用 RegEnumValue 函数,并将 dwIndex 参数设置为零。 然后,应用程序应递增 dwIndex 并调用 RegEnumValue 函数,直到函数返回ERROR_NO_MORE_ITEMS) 之前, (没有更多值。
应用程序还可以在首次调用函数时将 dwIndex 设置为最后一个值的索引,并递减索引,直到枚举索引为 0 的值。 若要检索最后一个值的索引,请使用 RegQueryInfoKey 函数。
使用 RegEnumValue 时,应用程序不应调用任何可能更改所查询的密钥的注册表函数。
如果数据具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型,则字符串可能未存储正确的 null 终止字符。 因此,即使函数返回ERROR_SUCCESS,应用程序也应该确保字符串在使用前正确终止;否则,它可能会覆盖缓冲区。 (请注意,REG_MULTI_SZ字符串应具有两个 null 终止字符。)
若要确定名称和数据缓冲区的最大大小,请使用 RegQueryInfoKey 函数。
示例
有关示例,请参阅 枚举注册表子项。
注意
winreg.h 标头将 RegEnumValue 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定。
要求
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
目标平台 | Windows |
标头 | winreg.h (包括 Windows.h) |
Library | Advapi32.lib |
DLL | Advapi32.dll |