Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function enumerates the values for the specified open registry key. This function copies one indexed value name and data block for the key each time it is called.

A remote application interface (RAPI) version of this function exists called CeRegEnumValue (RAPI).

Syntax 

LONG RegEnumValue( 
  HKEY 
hKey, 
  DWORD 
dwIndex, 
  LPWSTR 
lpValueName, 
  LPDWORD 
lpcchValueName, 
  LPDWORD 
lpReserved, 
  LPDWORD 
lpType, 
  LPBYTE 
lpData, 
  LPDWORD 
lpcbData 
);

Parameters

hKey

[in] Handle to a currently open key. or one of the following predefined reserved handle values:

  • HKEY_LOCAL_MACHINE

  • HKEY_CLASSES_ROOT

  • HKEY_CURRENT_USER

  • HKEY_USERS

The enumerated values are associated with the key identified by this parameter.

dwIndex

[in] Index of the value to retrieve. This parameter is set to zero for the first call to this function, and then be incremented for subsequent calls.

Because values are not ordered, any new value has an arbitrary index. This means that the function returns values in any order.

lpValueName

[out] Pointer to a buffer that receives the name of the value, including the terminating null character.

lpcchValueName

[in, out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpValueName. This size includes the terminating null character. When the function returns, the variable pointed to by this parameter contains the number of characters stored in the buffer. The count returned does not include the terminating null character.

lpReserved

[in] Reserved. Set to NULL.

lpType

[out] Pointer to a variable that receives the type code for the value entry. The following table shows possible values.

Value Description

REG_BINARY

Specifies binary data in any form.

REG_DWORD

Specifies a 32-bit number.

REG_DWORD_BIG_ENDIAN

Specifies a 32-bit number in big-endian format.

In big-endian format, a multibyte value is stored in memory from the highest byte to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78)in big-endian format.

REG_DWORD_LITTLE_ENDIAN

Specifies a 32-bit number in little-endian format. This is equivalent to REG_DWORD.

In little-endian format, a multibyte value is stored in memory from the lowest byte to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12)in little-endian format.

REG_EXPAND_SZ

Specifies a null-terminated string that contains unexpanded references to environment variables, for example, %PATH%. It is a Unicode or an ANSI string, depending on whether you use the Unicode or ANSI functions.

REG_LINK

Specifies a Unicode symbolic link. Used internally. Applications do not use this type.

REG_MULTI_SZ

Specifies an array of null-terminated strings, terminated by two null characters.

REG_NONE

No defined value type.

REG_RESOURCE_LIST

Specifies a device-driver resource list.

REG_SZ

Specifies a null-terminated Unicode string.

This parameter can be set to NULL if the type code is not required.

lpData

[out] Pointer to a buffer that receives the data for the value entry. This parameter can be NULL if the data is not required.

lpcbData

[in, out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by lpData. When the function returns, the variable pointed to by this parameter contains the number of bytes stored in the buffer. This parameter can be set to NULL only if lpDatais set to NULL.

Return Value

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call the FormatMessagefunction with the FORMAT_MESSAGE_FROM_SYSTEM flag set. The message resource is optional, so FormatMessagemight fail.

Remarks

To enumerate values, an application initially calls this function with dwIndexset to zero. The application then increments dwIndexand calls this function until there are no more values. that is, until the function returns ERROR_NO_MORE_ITEMS.

The application can also set dwIndexto the index of the last value on the first call to the function and decrement the index until the value with index zero is enumerated. To retrieve the index of the last value, use the RegQueryInfoKeyfunction.

While using this function, an application should not call any registry functions that might change the key being enumerated.

To check the maximum size of the name and data buffers, use the RegQueryInfoKeyfunction.

Requirements

Header winreg.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also