Функция 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 .
Примечание
В устаревших версиях 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 |