Функция RegGetValueA (winreg.h)
Извлекает тип и данные для указанного значения реестра.
Синтаксис
LSTATUS RegGetValueA(
[in] HKEY hkey,
[in, optional] LPCSTR lpSubKey,
[in, optional] LPCSTR lpValue,
[in, optional] DWORD dwFlags,
[out, optional] LPDWORD pdwType,
[out, optional] PVOID pvData,
[in, out, optional] LPDWORD pcbData
);
Параметры
[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_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpSubKey
Путь к разделу реестра относительно ключа, указанного параметром hkey . Значение реестра будет получено из этого подраздела.
Путь не учитывает регистр.
Если этот параметр имеет значение NULL или пустую строку "", значение будет считываться из ключа, указанного самим ключом hkey .
[in, optional] lpValue
Имя значения реестра.
Если этот параметр имеет значение NULL или пустую строку "", функция извлекает тип и данные для неименованного или значения по умолчанию ключа, если таковой имеется. Ключи не имеют автоматически неименованного значения или значения по умолчанию, а неименованные значения могут иметь любой тип.
Дополнительные сведения см. в разделе Ограничения размера элементов реестра.
[in, optional] dwFlags
Флаги, ограничивающие тип данных значения для запроса. Если тип данных значения не соответствует этим критериям, функция завершается ошибкой. Этот параметр может быть одним или несколькими из следующих значений.
Этот параметр также может включать одно или несколько из следующих значений.
| Значение | Значение |
|---|---|
|
Не развертывайте строки среды автоматически, если значение имеет тип REG_EXPAND_SZ. |
|
Если параметр pvData не имеет значение NULL, при сбое присвойте содержимому буфера значения нулей. |
|
Если lpSubKey не имеет значение NULL, откройте подраздел, который указывает lpSubKey с правами доступа KEY_WOW64_64KEY.
Дополнительные сведения об этих правах доступа см. в разделе Безопасность раздела реестра и права доступа.
Вы не можете указать RRF_SUBKEY_WOW6464KEY в сочетании с RRF_SUBKEY_WOW6432KEY. |
|
Если lpSubKey не имеет значение NULL, откройте подраздел, который указывает lpSubKey с правами доступа KEY_WOW64_32KEY.
Дополнительные сведения об этих правах доступа см. в разделе Безопасность раздела реестра и права доступа.
Вы не можете указать RRF_SUBKEY_WOW6432KEY в сочетании с RRF_SUBKEY_WOW6464KEY. |
[out, optional] pdwType
Указатель на переменную, получающую код, указывающий тип данных, хранящихся в указанном значении. Список возможных кодов типов см. в разделе Типы значений реестра. Этот параметр может иметь значение NULL , если тип не является обязательным.
[out, optional] pvData
Указатель на буфер, получающий данные значения. Этот параметр может иметь значение NULL , если данные не требуются.
Если данные являются строкой, функция проверяет наличие завершающего символа NULL . Если он не найден, строка сохраняется с признаком конца null , если буфер достаточно велик для размещения дополнительного символа. В противном случае функция завершается сбоем и возвращает ERROR_MORE_DATA.
[in, out, optional] pcbData
Указатель на переменную, указывающую размер буфера, на который указывает параметр pvData , в байтах. Когда функция возвращает, эта переменная содержит размер данных, скопированных в pvData.
Параметр pcbData может иметь значение NULL , только если pvData имеет значение NULL.
Если данные имеют тип REG_SZ, REG_MULTI_SZ или REG_EXPAND_SZ, этот размер включает все завершающие символы NULL или символы. Дополнительные сведения см. в подразделе "Примечания".
Если буфер, заданный параметром pvData , недостаточно велик для хранения данных, функция возвращает ERROR_MORE_DATA и сохраняет требуемый размер буфера в переменной, на которую указывает pcbData. В этом случае содержимое буфера pvData равно нулю, если dwFlags указывает RRF_ZEROONFAILURE и не определено в противном случае.
Если pvData имеет значение NULL, а pcbData — не NULL, функция возвращает ERROR_SUCCESS и сохраняет размер данных в байтах в переменной, на которую указывает pcbData. Это позволяет приложению определить оптимальный способ выделения буфера для данных значения.
Если hKey указывает HKEY_PERFORMANCE_DATA и буфер pvData недостаточно велик, чтобы содержать все возвращаемые данные, функция возвращает ERROR_MORE_DATA и значение, возвращаемое с помощью параметра pcbData , не определено. Это связано с тем, что размер данных о производительности может меняться от одного вызова к другому. В этом случае необходимо увеличить размер буфера и снова вызвать RegGetValue , передав обновленный размер буфера в параметре pcbData . Повторяйте это, пока функция не будет выполнена успешно. Для отслеживания размера буфера необходимо сохранить отдельную переменную, так как значение, возвращаемое pcbData , непредсказуемо.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки.
Если буфер pvData слишком мал для получения значения, функция возвращает ERROR_MORE_DATA.
Если значение реестра lpValue не существует, функция возвращает ERROR_FILE_NOT_FOUND.
Если dwFlags задает сочетание RRF_SUBKEY_WOW6464KEY и RRF_SUBKEY_WOW6432KEY, функция возвращает ERROR_INVALID_PARAMETER.
Комментарии
Приложение обычно вызывает RegEnumValue для определения имен значений, а затем RegGetValue для получения данных для имен.
Если данные имеют тип REG_SZ, REG_MULTI_SZ или REG_EXPAND_SZ и используется версия ANSI этой функции (путем явного вызова RegGetValueA или путем не определения ЮНИКОДа перед включением файла Windows.h), эта функция преобразует сохраненную строку Юникода в строку ANSI, прежде чем копировать ее в буфер, на который указывает pvData.
При вызове этой функции с ключом hkey , для которого задан дескриптор HKEY_PERFORMANCE_DATA и строка значения указанного объекта, возвращаемая структура данных иногда содержит незапросенные объекты. Не удивляйтесь; Это нормальное поведение. Всегда следует ожидать обхода возвращаемой структуры данных для поиска запрошенного объекта.
Обратите внимание, что операции, которые обращаются к определенным разделам реестра, перенаправляются. Дополнительные сведения см. в статье Виртуализация реестра и 32-разрядные и 64-разрядные данные приложений в реестре.
Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0600 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.
Примечание
Заголовок winreg.h определяет RegGetValue как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows Vista, Windows XP Professional x64 Edition |
| Минимальная версия сервера | Windows Server 2008, Windows Server 2003 с пакетом обновления 1 (SP1) |
| Целевая платформа | Windows |
| Header | winreg.h (включая Windows.h) |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по