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, ByVal lpReserved As Long, lpType As Long, lpData As Byte, lpcbData As Long) As Long

Platforms

Description & Usage

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.

Return Value

If successful, the function returns 0. If an error occured, the function returns a non-zero error code.

Visual Basic-Specific Issues

When passing 0 for lpData or lpcbData, the ByVal keyword must be placed in front if the 0 (i.e., use ByVal 0 instead of just 0).

Parameters

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 base keys (identified by identicially named flags):
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95, 98 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT, 2000 only)
HKEY_USERS
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.
lpType
Receives exactly one of the following flags identifying the data type of the value:
REG_BINARY
A non-text sequence of bytes.
REG_DWORD
Same as REG_DWORD_LITTLE_ENDIAN.
REG_DWORD_BIG_ENDIAN
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, putting the most significant byte first in memory.
REG_DWORD_LITTLE_ENDIAN
A 32-bit integer stored in little-endian format. This is the way Intel-based computers store numbers, putting the least significant byte first in memory.
REG_EXPAND_SZ
A null-terminated string which contains unexpanded environment variables.
REG_LINK
A Unicode symbolic link.
REG_MULTI_SZ
A series of strings, each separated by a null character and the entire set terminated by a two null characters.
REG_NONE
No data type.
REG_RESOURCE_LIST
A list of resources in the resource map.
REG_SZ
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.
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.

Constant Definitions

Const HKEY_CLASSES_ROOT = &H80000000
Const HKEY_CURRENT_CONFIG = &H80000005
Const HKEY_CURRENT_USER = &H80000001
Const HKEY_DYN_DATA = &H80000006
Const HKEY_LOCAL_MACHINE = &H80000002
Const HKEY_PERFORMANCE_DATA = &H80000004
Const HKEY_USERS = &H80000003
Const REG_BINARY = 3
Const REG_DWORD = 4
Const REG_DWORD_BIG_ENDIAN = 5
Const REG_DWORD_LITTLE_ENDIAN = 4
Const REG_EXPAND_SZ = 2
Const REG_LINK = 6
Const REG_MULTI_SZ = 7
Const REG_NONE = 0
Const REG_RESOURCE_LIST = 8
Const REG_SZ = 1

Example

List the values under the 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.

The example runs when the user clicks button Command1. To use this example, then, you must first place a command button named Command1 on a form window.

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function RegEnumValue Lib "advapi32.dll" Alias "RegEnumValueA" (ByVal hKey _
	As Long, ByVal dwIndex As Long, ByVal lpValueName As String, lpcbValueName As Long, _
	ByVal lpReserved As Long, lpType As Long, lpData As Byte, lpcbData As Long) As Long
Public Declare Function RegOpenKeyEx Lib "advapi32.dll" Alias "RegOpenKeyExA" (ByVal hKey _
	As Long, ByVal lpSubKey As String, ByVal ulOptions As Long, ByVal samDesired _
	As Long, phkResult As Long) As Long
Public Declare Function RegCloseKey Lib "advapi32.dll" (ByVal hKey As Long) As Long
Public Declare Sub CopyMemory Lib "kernel32.dll" Alias "RtlMoveMemory" (Destination As Any, _
	Source As Any, ByVal Length As Long)
Public Const HKEY_LOCAL_MACHINE = &H80000002
Public Const KEY_QUERY_VALUE = &H1
Public Const REG_SZ = 1
Public Const REG_BINARY = 3

' *** Place the following code inside a form window. ***

Private Sub Command1_Click()
	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
		' 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, 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.
				' We subtract one because we don't want the trailing null.
				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 
				' sapces.  Use the datastring buffer to allow us to assure each byte
				' is represented by a two-character string.
				Debug.Print "  Data (binary):";
				For c = 0 To datalen - 1  ' loop through returned information
					datastring = Hex(data(c))  ' convert value into hex
					' If needed, add leading zero(s).
					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(hkey)
End Sub

See Also

RegEnumKeyEx

Category

Registry

Go back to the alphabetical Function listing.
Go back to the Reference section index.


Last Modified: September 24, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/regenumvalue.html