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

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

Синтаксис

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 .

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

[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 , только если lpData имеет значение NULL.

Если данные имеют тип 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 и вызывать функцию 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 .

Примеры

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

Требования

См. также раздел

RegCreateKeyEx

RegEnumKeyEx

RegOpenKeyEx

RegQueryInfoKey

Функции реестра

Общие сведения о реестре