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

Статья
11/20/2024

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

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

Синтаксис

LSTATUS RegQueryValueW(
  [in]                HKEY    hKey,
  [in, optional]      LPCWSTR lpSubKey,
  [out, optional]     LPWSTR  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

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

Если lpValuenull, а 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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winreg.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll