Функция 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

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

Этот параметр также может включать одно или несколько из следующих значений.

[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.

Требования

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

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegOpenKeyEx

RegQueryInfoKey

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

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