Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function RegEnumKeyEx Lib "advapi32.dll" Alias "RegEnumKeyExA" (ByVal hKey As Long, ByVal dwIndex As Long, ByVal lpName As String, lpcbName As Long, lpReserved As Long, ByVal lpClass As String, lpcbClass As Long, lpftLastWriteTime As FILETIME) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

RegEnumKeyEx enumerates all of the subkeys under a given key. The function retrieves the subkey name, class name, and last write time of each subkey. The key under which the subkeys are enumerated must have been opened with subkey-enumeration access (see the example). The program must use the function in a loop, incrementing the index value (which determines which subkey is identified) until the list has been exhaused. The subkeys are not retrieved in any clear order.

Return Value

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

Visual Basic-Specific Issues

None.

Parameters

hKey

A handle to the open registry key containing the subkeys to be enumerated (having been opened with subkey-enumeration access). This could also be one of the following flags identifying a predefined base keys:

HKEY_CLASSES_ROOT: The HKEY_CLASSES_ROOT base key.
HKEY_CURRENT_CONFIG: The HKEY_CURRENT_CONFIG base key.
HKEY_CURRENT_USER: The HKEY_CURRENT_USER base key.
HKEY_DYN_DATA: Windows 95, 98: The HKEY_DYN_DATA base key.
HKEY_LOCAL_MACHINE: The HKEY_LOCAL_MACHINE base key.
HKEY_PERFORMANCE_DATA: Windows NT, 2000: The HKEY_PERFORMANCE_DATA base key.
HKEY_USERS: The HKEY_USERS base key.

dwIndex

The index of the particular subkey to retrieve information about. Valid indices begin with 0 and go up to one less than the number of subkeys.

lpName

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

lpcbName

The size of the string passed as lpName. This also receives the length of the string the function places in lpName.

lpReserved

Reserved -- set to 0. Visual Basic users must use the ByVal keyword immediately before the 0.

lpClass

String which receives the name of the subkey's class. This must be initialized to a sufficient size to receive the string.

lpcbClass

The size of the string passed as lpClass. This also receives the length of the string the function places in lpClass.

lpftLastWriteTime

Receives the time and date on which the subkey was last written to.

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

Example

' This code is licensed according to the terms and conditions listed here. ' Enumerate the subkeys under HKEY_LOCAL_MACHINE\Software. The name ' and class of each subkey is displayed for the user. Note the use of the loop which ' starts at 0 and keeps incrementing the index until no more subkeys exist. Dim keyname As String ' receives name of each subkey Dim keylen As Long ' length of keyname Dim classname As String ' receives class of each subkey Dim classlen As Long ' length of classname Dim lastwrite As FILETIME ' receives last-write-to time, but we ignore it here Dim hkey As Long ' handle to the HKEY_LOCAL_MACHINE\Software key Dim index As Long ' counter variable for index Dim retval As Long ' function's return value ' Open the desired registry key. Note the access level requested. retval = RegOpenKeyEx(HKEY_LOCAL_MACHINE, "Software", 0, KEY_ENUMERATE_SUB_KEYS, hkey) ' Test to make sure the key was opened successfully. If retval <> 0 Then Debug.Print "Registry key could not be opened -- aborting." End ' terminate the program End If ' List through each possible subkey. Note how the strings receiving the information ' must be reinitialized each loop iteration. index = 0 ' initial index value While retval = 0 ' while we keep having success (retval equals 0 from the above API call) keyname = Space(255): classname = Space(255) ' make room in string buffers keylen = 255: classlen = 255 ' identify the allocated space ' Get information about the next subkey, if one exists. retval = RegEnumKeyEx(hkey, index, keyname, keylen, ByVal 0, classname, classlen, lastwrite) If retval = 0 ' only display info if another subkey was found ' Extract the useful information from the string buffers. keyname = Left(keyname, keylen) ' trim off the excess space classname = Left(classname, classlen) ' Display the returned information. Debug.Print "HKEY_LOCAL_MACHINE\Software\"; keyname ' display full subkey name Debug.Print " (class: "; classname ' display subkey's class End If index = index + 1 ' increment the index counter Wend ' end the loop ' Close the registry key after enumeration is complete. retval = RegCloseKey(hkey)