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

Статья
11/20/2024

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

Примечание Эта функция предоставляется только для совместимости с 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, в TCHARs. Чтобы определить требуемый размер буфера, используйте функцию regQueryInfoKey , чтобы определить размер самого большого подраздела ключа, определяемого параметром hKey.

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

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

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

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

Замечания

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winreg.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll