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

Статья
03/11/2023

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

Синтаксис

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 , содержит количество символов, хранящихся в буфере, не включая завершающий символ NULL .

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

lpReserved

Этот параметр зарезервирован и должен иметь значение NULL.

[in, out] lpClass

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

[in, out, optional] lpcchClass

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

[out, optional] lpftLastWriteTime

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

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

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

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

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

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

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

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

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

Примечание

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

Примеры

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

Примечание

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

Требования


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