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

LONG WINAPI RegEnumValue(
  __in         HKEY hKey,
  __in         DWORD dwIndex,
  __out        LPTSTR lpValueName,
  __inout      LPDWORD lpcchValueName,
  __reserved   LPDWORD lpReserved,
  __out_opt    LPDWORD lpType,
  __out_opt    LPBYTE lpData,
  __inout_opt  LPDWORD lpcbData
);

Parameters

hKey [in]

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

dwIndex [in]

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.

lpValueName [out]

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.

lpcchValueName [in, out]

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.

lpReserved

This parameter is reserved and must be NULL.

lpType [out, optional]

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.

lpData [out, optional]

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.

lpcbData [in, out, optional]

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 reeives 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.

Registry value names are limited to 32767 bytes. The ANSI version of this function treats this param as a USHORT value. Therefore, if you specify a value greater than 32767 bytes, there is an overflow and the function may return ERROR_MORE_DATA.

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 lpData buffer 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.

Examples

For an example, see Enumerating Registry Subkeys.

Requirements

See Also

RegCreateKeyEx

RegEnumKeyEx

Registry Functions

Registry Overview

RegOpenKeyEx

RegQueryInfoKey

Send comments about this topic to Microsoft

Build date: 11/19/2009