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

Статья
11/20/2024

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

Синтаксис

LSTATUS RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   lpValueName,
  [in, out]           LPDWORD lpcchValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

Параметры

[in] hKey

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

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

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

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

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

[out] lpValueName

Указатель на буфер, который получает имя значения в виде строки null-terminated.

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

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

[in, out] lpcchValueName

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

Если буфер, указанный lpValueName недостаточно велик для хранения данных, функция возвращает ERROR_MORE_DATA и размер буфера в переменной, на которую указывает lpValueName. В этом случае содержимое lpcchValueName не определено.

Имена значений реестра ограничены 32 767 байтами. Версия ANSI этой функции обрабатывает этот параметр как значение SHORT. Таким образом, если указать значение, превышающее 32 767 байт, возникает переполнение, а функция может возвращать ERROR_MORE_DATA.

lpReserved

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

[out, optional] lpType

Указатель на переменную, которая получает код, указывающий тип данных, хранящихся в указанном значении. Список возможных кодов типов см. в типах значений реестра. Параметр lpType может быть NULL, если код типа не требуется.

[out, optional] lpData

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

Если lpData NULL и lpcbData неNULL, функция сохраняет размер данных в байтах, указываемой на lpcbData. Это позволяет приложению определить оптимальный способ выделения буфера для данных.

[in, out, optional] lpcbData

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

Этот параметр может быть NULL только в том случае, если lpDataNULL.

Если данные имеют тип REG_SZ, REG_MULTI_SZ или REG_EXPAND_SZ, этот размер включает в себя все символы или символы null. Дополнительные сведения см. в разделе "Примечания".

Если буфер, указанный lpData недостаточно велик для хранения данных, функция возвращает ERROR_MORE_DATA и сохраняет требуемый размер буфера в переменной, на которую указывает lpcbData. В этом случае содержимое lpData не определено.

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

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

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

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

Замечания

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

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

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

Если данные имеют REG_SZ, REG_MULTI_SZ или тип REG_EXPAND_SZ, строка может не храниться с соответствующими символами, null-конца. Таким образом, даже если функция возвращает ERROR_SUCCESS, приложение должно убедиться, что строка будет правильно завершена перед его использованием; в противном случае он может перезаписать буфер. (Обратите внимание, что строки REG_MULTI_SZ должны иметь два null-конечные символы.)

Чтобы определить максимальный размер буферов имен и данных, используйте функцию RegQueryInfoKey.

Заметка

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

Примеры

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

Заметка

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

Требования

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