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

Статья
03/08/2023

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

Синтаксис

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 .

Примечание

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

Примеры

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

Примечание

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

Требования


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