注册表枚举键值

 

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

A remote application interface (RAPI) version of this function exists, and it is called CeRegEnumKeyEx (RAPI).

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_CLASSES_ROOT
• HKEY_CURRENT_USER
• HKEY_LOCAL_MACHINE
• HKEY_USERS

The enumerated keys are subkeys of the key identified by hKey.

dwIndex

[in] Index of the subkey to retrieve. This parameter should be zero for the first call to the RegEnumKeyEx function and then incremented for subsequent calls.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return 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 the lpName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcName 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 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 the lpClass parameter. The size should include the terminating null character. When the function returns, lpcbClass contains the number of characters stored in the buffer. The count returned does not include the terminating null character. This parameter can be NULL only if lpClass is NULL.

lpftLastWriteTime

[in] Ignored; set to NULL.

Return Values

ERROR_SUCCESS indicates success. A return value of ERROR_MORE_DATA indicates that thelpName 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 FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set. The message resource is optional; therefore, if you callFormatMessage it could fail.

Remarks

To enumerate subkeys, an application should initially call the RegEnumKeyEx function with thedwIndex parameter set to zero. An application should then increment thedwIndex parameter and call RegEnumKeyEx until there are no more subkeys (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 the function and decrement the index until the subkey with the index 0 is enumerated. To retrieve the index of the last subkey, use theRegQueryInfoKey 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 theRegCreateKeyEx orRegOpenKeyEx function to open the key identified byhKey.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winreg.h.
Link Library: Coredll.lib.

 

参数

hKey

已打开键的句柄,打开该键时应该包含KEY_ENUMERATE_SUB_KEYS权限,更多信息,查看Registry Key Security and Access Rights.该句柄可由RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx,或 RegOpenKeyTransacted返回.或者,使用一下预设值:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

dwIndex

返回子键的索引.当第一次调用该函数时,此参数必须设为0,在尔后的调用中逐次增加.

由于子键是无序的,一个新的子键可能得到任意的索引.这个函数可能以任何顺序返回子键.

lpName

一个指针,指向接受子键名的缓冲区,包含null(即char(0))作为终止符.函数仅仅向该缓冲区返回子键名,而不是整个子键的树状结构.更多信息,查看Registry Element Size Limits.

lpcName

指向一个指明lpName缓冲区大小的变量的指针,使用TCHARs形式.大小应该包括终止符Null.当函数返回时,变量将指向一个指明lpName包含字符数的指针.这个返回值没有数上终止符Null.

lpReserved

该参数为预留参数,请设为Null.

lpClass

一个指针,指向接受子键类名(Class String)的缓冲区,包含null(即char(0))作为终止符.参数可以为Null

lpcClass

指向一个指明lpClass缓冲区大小的变量的指针,使用TCHARs形式.大小应该包括终止符Null.当函数返回时,变量将指向一个指明lpClass包含字符数的指针.这个返回值没有数上终止符Null.如果Lpclass为Null,该参数也应为Null

lpftLastWriteTime

指向一个变量的指针,它将接收到被枚举的子键上一次改写的时间,参数可以为Null

返回值

如果没有更多可用的子键,返回ERROR_NO_MORE_ITEMS.如果lpName缓冲区太小,返回ERROR_MORE_DATA.

如果函数无异常,返回ERROR_SUCCESS,否则将返回一个系统错误代码(system error code).

注意

为了枚举子键,应用程序在首次调用RegEnumKeyEx函数时dwIndex 参数必须为0.其后逐次增加,直到没有更多的子键(返回ERROR_NO_MORE_ITEMS)

应用程序也可以在第一次调用函数时,将dwIndex 参数设置为最后一个子键的索引,其后逐次减少到0.获得最后一个子键的索引,使用RegQueryInfoKey函数

注意关于当前注册表项的权限操作是重定向的(Note that operations that access certain registry keys are redirected.) 更多信息,查看 Registry Virtualization 和 32-bit and 64-bit Application Data in the Registry.

实例代码

Enumerating Registry Subkeys.

必需环境

个人用户	Windows Vista, Windows XP, or Windows 2000 Professional.
服务器	Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
头文件	定义在Winreg.h; 包含于Windows.h.
库	使用Advapi32.lib.
DLL	必须Advapi32.dll.
Unicode	分为RegEnumKeyExW (Unicode) 和 RegEnumKeyExA (ANSI).