Функция RegEnumKeyA (winreg.h)

Статья
08/27/2023

Перечисляет подразделы указанного открытого раздела реестра. Функция получает имя одного подраздела при каждом вызове.

Примечание Эта функция предоставляется только для совместимости с 16-разрядными версиями Windows. Приложения должны использовать функцию RegEnumKeyEx .

Синтаксис

LSTATUS RegEnumKeyA(
  [in]  HKEY  hKey,
  [in]  DWORD dwIndex,
  [out] LPSTR lpName,
  [in]  DWORD cchName
);

Параметры

[in] hKey

Дескриптор открытого раздела реестра. Ключ должен быть открыт с правом доступа KEY_ENUMERATE_SUB_KEYS. Дополнительные сведения см. в разделе Безопасность раздела реестра и права доступа.

Этот дескриптор возвращается функцией RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx или RegOpenKeyTransacted . Это также может быть один из следующих предопределенных ключей:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in] dwIndex

Индекс извлекаемого подраздела hKey . Это значение должно быть равно нулю для первого вызова функции RegEnumKey , а затем увеличиваться для последующих вызовов.

Так как подразделы не упорядочены, любой новый подраздел будет иметь произвольный индекс. Это означает, что функция может возвращать подразделы в любом порядке.

[out] lpName

Указатель на буфер, который получает имя подраздела, включая завершающий символ NULL. Эта функция копирует в буфер только имя подраздела, а не полную иерархию ключей.

Дополнительные сведения см. в разделе Ограничения размера элементов реестра.

[in] cchName

Размер буфера, на который указывает параметр lpName , в TCHAR. Чтобы определить требуемый размер буфера, используйте функцию RegQueryInfoKey , чтобы определить размер самого большого подраздела для ключа, определяемого параметром hKey .

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки. Если доступных подразделов больше нет, функция возвращает ERROR_NO_MORE_ITEMS.

Если буфер lpName слишком мал для получения имени ключа, функция возвращает ERROR_MORE_DATA.

Для перечисления подразделов приложение должно сначала вызвать функцию RegEnumKey с параметром dwIndex , равным нулю. Затем приложение должно увеличить параметр dwIndex и вызывать функцию RegEnumKey , пока не будет больше подразделов (то есть функция возвращает ERROR_NO_MORE_ITEMS).

Приложение также может присвоить dwIndex индексу последнего ключа при первом вызове функции и уменьшать индекс до перечисления подраздела с индексом 0. Чтобы получить индекс последнего подраздела, используйте RegQueryInfoKey.

Хотя приложение использует функцию RegEnumKey , оно не должно выполнять вызовы каких-либо функций регистрации, которые могут изменить запрашиваемый ключ.

Примечание

Заголовок winreg.h определяет RegEnumKey в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winreg.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll