RegEnumValue

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

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 lpData is 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 FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag set. The message resource is optional, so FormatMessage might fail.

Remarks

To enumerate values, an application initially calls this function with dwIndex set to zero. The application then increments dwIndex and calls this function until there are no more values. that is, 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 zero is enumerated. To retrieve the index of the last value, use the RegQueryInfoKey function.

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 RegQueryInfoKey function.

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

Reference

Registry Functions
RegCreateKeyEx
RegEnumKeyEx
RegOpenKeyEx
RegQueryInfoKey

Other Resources

State and Notifications Broker