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

Статья
08/27/2023

Извлекает данные, связанные с значением по умолчанию или без имени указанного раздела реестра. Данные должны быть строкой, заканчивающейся null.

Примечание Эта функция предоставляется только для совместимости с 16-разрядными версиями Windows. Приложения должны использовать функцию RegQueryValueEx .

Синтаксис

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  lpcbData
);

Параметры

[in] hKey

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

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

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in, optional] lpSubKey

Имя подраздела параметра hKey , для которого извлекается значение по умолчанию.

В именах ключей регистр не учитывается.

Если этот параметр имеет значение NULL или указывает на пустую строку, функция получает значение по умолчанию для ключа, определяемого hKey.

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

[out, optional] lpData

Указатель на буфер, получающий значение по умолчанию указанного ключа.

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

[in, out, optional] lpcbData

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

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

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

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

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

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

Если буфер lpValue слишком мал для получения значения, функция возвращает ERROR_MORE_DATA.

Если используется версия ANSI этой функции (путем явного вызова RegQueryValueA или не определения ЮНИКОДа перед включением файла Windows.h), эта функция преобразует сохраненную строку Юникода в строку ANSI перед копированием в буфер, заданный параметром lpValue .

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

Обратите внимание, что операции, которые обращаются к определенным разделам реестра, перенаправляются. Дополнительные сведения см. в статье Виртуализация реестра и 32-разрядные и 64-разрядные данные приложений в реестре.

Примечание

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

Требования


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