RegEnumKey

3.1

  #include <shellapi.h>    

  LONG RegEnumKey(hkey, iSubkey, lpszBuffer, cbBuffer)    
  HKEY hkey; /* handle of key to query */
  DWORD iSubkey; /* index of subkey to query */
  LPSTR lpszBuffer; /* address of buffer for subkey string */
  DWORD cbBuffer; /* size of subkey buffer */

The RegEnumKey function enumerates the subkeys of a specified key.

Parameters

hkey

Identifies an open key (which can be HKEY_CLASSES_ROOT) for which subkey information is retrieved.

iSubkey

Specifies the index of the subkey to retrieve. This value should be zero for the first call to the RegEnumKey function.

lpszBuffer

Points to a buffer that contains the name of the subkey when the function returns. This function copies only the name of the subkey, not the full key hierarchy, to the buffer.

cbBuffer

Specifies the size, in bytes, of the buffer pointed to by the lpszBuffer parameter.

Return Value

The return value is ERROR_SUCCESS if the function is successful. Otherwise, it is an error value.

Comments

The first parameter of the RegEnumKey function must specify an open key. Applications typically precede the call to the RegEnumKey function with a call to the RegOpenKey function and follow it with a call to the RegCloseKey function. Calling RegOpenKey and RegCloseKey is not necessary when the first parameter is HKEY_CLASSES_ROOT, because this key is always open and available; however, calling RegOpenKey and RegCloseKey in this case is a time optimization. While an application is using the RegEnumKey function, it should not make calls to any registration functions that might change the key being queried.

To enumerate subkeys, an application should initially set the iSubkey parameter to zero and then increment it on successive calls.

Example

The following example uses the RegEnumKey function to put the values associated with top-level keys into a list box:

HKEY hkRoot;
char szBuff[80], szValue[80];
static DWORD dwIndex;
LONG cb;

if (RegOpenKey(HKEY_CLASSES_ROOT, NULL, &hkRoot) == ERROR_SUCCESS) {
    for (dwIndex = 0; RegEnumKey(hkRoot, dwIndex, szBuff,
             sizeof(szBuff)) == ERROR_SUCCESS; ++dwIndex) {
        if (*szBuff == '.')
            continue;
        cb = sizeof(szValue);
        if (RegQueryValue(hkRoot, (LPSTR) szBuff, szValue,
                &cb) == ERROR_SUCCESS)
            SendDlgItemMessage(hDlg, ID_ENUMLIST, LB_ADDSTRING, 0,
                (LONG) (LPSTR) szValue);
    }
    RegCloseKey(hkRoot);
}

See Also

RegQueryValue