RegEnumValueA 函数 (winreg.h)

项目
08/27/2023

枚举指定打开的注册表项的值。每次调用该函数时，该函数都会为键复制一个索引值名称和数据块。

语法

LSTATUS RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   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 字符。

如果 lpValueName 指定的缓冲区不够大，无法容纳数据，则函数将返回ERROR_MORE_DATA并且 lpValueName 指向的变量中的缓冲区大小不会更改。在这种情况下， 未定义 lpcchValueName 的内容。

注册表值名称限制为 32，767 个字节。此函数的 ANSI 版本将此参数视为 SHORT 值。因此，如果指定的值大于 32，767 个字节，则存在溢出，函数可能会返回ERROR_MORE_DATA。

lpReserved

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

[out, optional] lpType

指向变量的指针，该变量接收指示存储在指定值中的数据类型的代码。有关可能的类型代码的列表，请参阅注册表值类型。如果不需要类型代码， 则 lpType 参数可以为 NULL 。

[out, optional] lpData

指向接收值条目数据的缓冲区的指针。如果不需要数据，此参数可以为 NULL 。

如果 lpData 为 NULL 且 l中的应用数据 为非 NULL，则该函数会将数据的大小（以字节为单位）存储在 l中的应用数据（以字节为单位）。这使应用程序能够确定为数据分配缓冲区的最佳方式。

[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 Data 指向的变量中。在这种情况下， lpData 的内容未定义。

返回值

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

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

如果 lpValueName 或 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 函数。

注意

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

示例

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

注意

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

要求


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