RegEnumKeyEx

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function enumerates subkeys of the specified open registry key. This function obtains information about one subkey each time it is called, and it obtains the class name of the subkey and the time it was last modified.

A remote application interface (RAPI) version of this function exists called CeRegEnumKeyEx (RAPI).

Syntax

LONG RegEnumKeyEx(
  HKEY hKey, 
  DWORD dwIndex, 
  LPWSTR lpName, 
  LPDWORD lpcName, 
  LPDWORD lpReserved, 
  LPWSTR lpClass, 
  LPDWORD lpcbClass, 
  PFILETIME lpftLastWriteTime 
); 

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 keys are subkeys of the key identified by this parameter.

• dwIndex
  [in] Index of the subkey to retrieve. This parameter is set to zero for the first call to the RegEnumKeyEx function, and then incremented for subsequent calls.

  Because subkeys are not ordered, any new subkey has an arbitrary index. This means that this function returns subkeys in any order.

• lpName
  [out] Pointer to a buffer that receives the name of the subkey, including the terminating null character. The function copies only the name of the subkey, not the full key hierarchy, to the buffer.

• lpcName
  [in, out] Pointer to a variable that specifies the size, in characters, of the buffer specified by lpName. This size includes the terminating null character. When this 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.

• lpClass
  [out] Pointer to a buffer that contains the class of the enumerated subkey when the function returns. This parameter can be set to NULL if the class is not required.

• lpcbClass
  [in, out] Pointer to a variable that specifies the size, in characters, of the buffer specified by lpClass. The size includes the terminating null character. When the function returns, this parameter contains the number of characters stored in the buffer. The count returned does not include the terminating null character. This parameter can be set to NULL only if lpClass is set to NULL.

• lpftLastWriteTime
  [in] Ignored. Set to NULL.

Return Value

ERROR_SUCCESS indicates success. A return value of ERROR_MORE_DATA indicates that the lpName buffer is too small to receive the name of the key. 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 subkeys, an application initially calls this function with dwIndex set to zero. An application then increments dwIndex and calls this function until there are no more subkeys, that is, until the function returns ERROR_NO_MORE_ITEMS.

An application can also set dwIndex to the index of the last subkey on the first call to this function and decrement the index until the subkey with the index zero is enumerated. To retrieve the index of the last subkey, use the RegQueryInfoKey function.

While an application is using the RegEnumKeyEx function, it should not make calls to any registry functions that might change the key being enumerated. Use the RegCreateKeyEx or the RegOpenKeyEx function to open the key identified by hKey.

Requirements

See Also

Reference

Registry Functions
RegCreateKeyEx
RegDeleteKey
RegOpenKeyEx
RegQueryInfoKey

Other Resources

State and Notifications Broker