RegEnumValue Function

Declare Function RegEnumValue Lib "advapi32.dll" Alias "RegEnumValueA" (ByVal hkey As Long, ByVal dwIndex As Long, ByVal lpValueName As String, lpcbValueName As Long, lpReserved As Long, lpType As Long, lpData As Byte, lpcbData As Long) As Long

Platforms: Win 32s, Win 95/98, Win NT

RegEnumValues enumerates all of the values under a given registry key. The function must be used in a loop because each call only retrieves information about the value identified by the given index. Besides merely listing the names of each value, the function can also retrieve the data associated with each value. This data, which could be in any vaid registry data format, is placed in an array of bytes passed as lpData. It is the program's responsibility to correctly interpret the information. The key whose values are enumerated must have been opened with query-level access. The values which are enumerated are not retrived in any obvious order. The function returns 0 if successful, or a non-zero error code if an error occured.

hkey

A handle to the opened registry key containing the values to enumerate (having been opened with query-level access). This could also be exactly one of the following flags identifying one of the predefined base keys:

HKEY_CLASSES_ROOT = &H80000000

The HKEY_CLASSES_ROOT base key.

HKEY_CURRENT_CONFIG = &H80000005

The HKEY_CURRENT_CONFIG base key.

HKEY_CURRENT_USER = &H80000001

The HKEY_CURRENT_USER base key.

HKEY_DYN_DATA = &H80000006

The HKEY_DYN_DATA base key.

HKEY_LOCAL_MACHINE = &H80000002

The HKEY_LOCAL_MACHINE base key.

HKEY_PERFORMANCE_DATA = &H80000004

The HKEY_PERFORMANCE_DATA base key.

HKEY_USERS = &H80000003

The HKEY_USERS base key.

dwIndex

The index of the particular value to retrieve information about. Valid indices range from 0 to one less than the total number of values.

lpValueName

String which receives the name of the value whose information is being retrieved. This must be initialized to a sufficient size to receive the string.

lpcbValueName

The size of the string passed as lpValueName. This also receives the size of the string the function places inside of it.

lpReserved

Reserved -- set to 0. Visual Basic users must include the ByVal keyword explicitly.

lpType

Receives exactly one of the following flags identifying the data type of the value:

REG_BINARY = 3

A non-text sequence of bytes.

REG_DWORD = 4

Same as REG_DWORD_LITTLE_ENDIAN.

REG_DWORD_BIG_ENDIAN = 5

A 32-bit integer stored in big-endian format. This is the opposite of the way Intel-based computers normally store numbers -- the byte order is reversed.

REG_DWORD_LITTLE_ENDIAN = 4

A 32-bit integer stored in little-endian format. This is the way Intel-based computers store numbers.

REG_EXPAND_SZ = 2

A null-terminated string which contains unexpanded environment variables.

REG_LINK = 6

A Unicode symbolic link.

REG_MULTI_SZ = 7

A series of strings, each separated by a null character and the entire set terminated by a two null characters.

REG_NONE = 0

No data type.

REG_RESOURCE_LIST = 8

A list of resources in the resource map.

REG_SZ = 1

A string terminated by a null character.

lpData

A byte array receiving the data stored in the value. If you do not want to retrieve the data, set this parameter to 0. (Visual Basic users must include the ByVal keyword if setting this to 0.)

lpcbData

The size in bytes of the array passed as lpData. This also receives the size in bytes of the data placed into the array. If you do not want to retrieve any data, set this parameter to 0. (Visual Basic users must include the ByVal keyword if setting this to 0.)

Example:

' List the values under the following registry key:
' HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion
' Display the names of all values under the key.  Also display the values' data if they are
' either null-terminated strings or binary data.  (This example could be extended to include
' the rest of the registry data types, but it doesn't to save space).  Note how the
' byte array is used to buffer the data before it might be copied to the string.
Dim valuename As String  ' name of the value being retrieved
Dim valuelen As Long  ' length of valuename
Dim datatype As Long  ' receives data type of value
Dim data(0 To 254) As Byte  ' 255-byte data buffer for read information
Dim datalen As Long  ' size of data buffer information
Dim datastring As String  ' will receive data converted to a string, if necessary
Dim hkey As Long  ' handle to the registry key to enumerate the values of
Dim index As Long  ' counter for the index of the value to enumerate
Dim c As Long  ' counter variable
Dim retval As Long  ' functions' return value

' Open the registry key to enumerate the values of.
retval = RegOpenKeyEx(HKEY_LOCAL_MACHINE, "Software\Microsoft\Windows\CurrentVersion", 0, KEY_QUERY_VALUE, hkey)
' Check to see if an error occured.
If retval <> 0 Then
  Debug.Print "Registry key could not be opened -- aborting."
  End  ' abort the program
End If

' Begin enumerating the values.  Get each one, displaying its name.  If it's a null-
' terminated string or binary data, display it.  If not, say so.
index = 0  ' initialize the counter
While retval = 0  ' loop while successful -- retval is already 0 to begin with
  ' Initialize the value name buffer.
  valuename = Space(255)  ' 255-space buffer
  valuelen = 255  ' length of the string
  datalen = 255  ' size of data buffer
  ' Get the next value to be enumerated
  retval = RegEnumValue(hkey, index, valuename, valuelen, ByVal 0, datatype, data(0), datalen) 
  If retval = 0 Then  ' if successful, display information
    ' Extract the useful information from the value name buffer and display it.
    valuename = Left(valuename, valuelen)
    Debug.Print "Value Name: "; valuename
    ' Determine the data type of the value and display it.
    Select Case datatype
    Case REG_SZ  ' null-terminated string
      ' Copy the information from the byte array into the string via the memory copying
      ' function.  We subtract one because we don't want the trailing null.  (Note the necessary
      ' usage of ByVal when passing a string to the following function.)
      datastring = Space(datalen - 1)  ' make just enough room in the string
      CopyMemory ByVal datastring, data(0), datalen - 1  ' copy useful data
      Debug.Print "  Data (string): "; datastring
    Case REG_BINARY  ' binary data
      ' Display the hexadecimal values of each byte of data, separated by spaces.
      ' Use the datastring buffer to allow us to assure each byte is represented
      ' by a two-character string.
      Debug.Print "  Data (binary):";  ' get ready to output
      For c = 0 To datalen - 1  ' loop through returned information
        datastring = Hex(data(c))  ' convert value into hex
        ' If needed, add leading zero(s) to make to a two-character string.
        If Len(datastring) < 2 Then datastring = String(2 - Len(datastring), "0") & datastring
        Debug.Print " "; datastring;
      Next c
      Debug.Print  ' end the line
    Case Else  ' a data type this example doesn't handle
      Debug.Print "This example doesn't know how to read that kind of data."
    End Select
  End If
  index = index + 1  ' increment the index counter
Wend  ' end the loop

' Close the registry key.
retval = RegCloseKey

Related Call: RegEnumKeyEx
Category: Registry
Back to the index.