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

Статья
11/20/2024

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

Синтаксис

LSTATUS RegEnumKeyExA(
  [in]                HKEY      hKey,
  [in]                DWORD     dwIndex,
  [out]               LPSTR     lpName,
  [in, out]           LPDWORD   lpcchName,
                      LPDWORD   lpReserved,
  [in, out]           LPSTR     lpClass,
  [in, out, optional] LPDWORD   lpcchClass,
  [out, optional]     PFILETIME lpftLastWriteTime
);

Параметры

[in] hKey

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

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

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

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

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

[out] lpName

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

Если функция завершается ошибкой, данные не копируются в этот буфер.

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

[in, out] lpcchName

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

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

lpReserved

Этот параметр зарезервирован и должен быть null.

[in, out] lpClass

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

[in, out, optional] lpcchClass

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

[out, optional] lpftLastWriteTime

Указатель на структуру FILETIME, получающую время записи перечисленного подраздела. Этот параметр может быть NULL.

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

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

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

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

Замечания

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

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

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

Обратите внимание, что операции, обращаюющиеся к определенным разделам реестра, перенаправляются. Дополнительные сведения см. в разделе Виртуализация реестра и 32-разрядных и 64-разрядных данных приложений в реестре.

Заметка

В устаревших версиях Windows этот API также предоставляется kernel32.dll.

Примеры

Пример см. в разделе Перечисление подразделов реестра.

Заметка

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

Требования

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