RegEnumValueA function (winreg.h)
Enumerates the values for the specified open registry key. The function copies one indexed value name and data block for the key each time it is called.
Syntax
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
);
Parameters
[in] hKey
A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right. For more information, see Registry Key Security and Access Rights.
This handle is returned by the RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx, or RegOpenKeyTransacted function. It can also be one of the following predefined keys:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_PERFORMANCE_DATA
- HKEY_USERS
[in] dwIndex
The index of the value to be retrieved. This parameter should be zero for the first call to the RegEnumValue function and then be incremented for subsequent calls.
Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.
[out] lpValueName
A pointer to a buffer that receives the name of the value as a null-terminated string.
This buffer must be large enough to include the terminating null character.
For more information, see Registry Element Size Limits.
[in, out] lpcchValueName
A pointer to a variable that specifies the size of the buffer pointed to by the lpValueName parameter, in characters. When the function returns, the variable receives the number of characters stored in the buffer, not including the terminating null character.
If the buffer specified by lpValueName is not large enough to hold the data, the function returns ERROR_MORE_DATA and the buffer size in the variable pointed to by lpValueName is not changed. In this case, the contents of lpcchValueName are undefined.
Registry value names are limited to 32,767 bytes. The ANSI version of this function treats this parameter as a SHORT value. Therefore, if you specify a value greater than 32,767 bytes, there is an overflow and the function may return ERROR_MORE_DATA.
lpReserved
This parameter is reserved and must be NULL.
[out, optional] lpType
A pointer to a variable that receives a code indicating the type of data stored in the specified value. For a list of the possible type codes, see Registry Value Types. The lpType parameter can be NULL if the type code is not required.
[out, optional] lpData
A pointer to a buffer that receives the data for the value entry. This parameter can be NULL if the data is not required.
If lpData is NULL and lpcbData is non-NULL, the function stores the size of the data, in bytes, in the variable pointed to by lpcbData. This enables an application to determine the best way to allocate a buffer for the data.
[in, out, optional] lpcbData
A pointer to a variable that specifies the size of the buffer pointed to by the lpData parameter, in bytes. When the function returns, the variable receives the number of bytes stored in the buffer.
This parameter can be NULL only if lpData is NULL.
If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, this size includes any terminating null character or characters. For more information, see Remarks.
If the buffer specified by lpData is not large enough to hold the data, the function returns ERROR_MORE_DATA and stores the required buffer size in the variable pointed to by lpcbData. In this case, the contents of lpData are undefined.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a system error code. If there are no more values available, the function returns ERROR_NO_MORE_ITEMS.
If the buffer specified by lpValueName or lpData is too small to receive the value, the function returns ERROR_MORE_DATA.
Remarks
To enumerate values, an application should initially call the RegEnumValue function with the dwIndex parameter set to zero. The application should then increment dwIndex and call the RegEnumValue function until there are no more values (until the function returns ERROR_NO_MORE_ITEMS).
The application can also set dwIndex to the index of the last value on the first call to the function and decrement the index until the value with index 0 is enumerated. To retrieve the index of the last value, use the RegQueryInfoKey function.
While using RegEnumValue, an application should not call any registry functions that might change the key being queried.
If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, the string may not have been stored with the proper null-terminating characters. Therefore, even if the function returns ERROR_SUCCESS, the application should ensure that the string is properly terminated before using it; otherwise, it may overwrite a buffer. (Note that REG_MULTI_SZ strings should have two null-terminating characters.)
To determine the maximum size of the name and data buffers, use the RegQueryInfoKey function.
Note
On legacy versions of Windows, this API is also exposed by kernel32.dll.
Examples
For an example, see Enumerating Registry Subkeys.
Note
The winreg.h header defines RegEnumValue as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | winreg.h (include Windows.h) |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |