Функция RegQueryValueExW (winreg.h)
Извлекает тип и данные для указанного имени значения, связанного с открытым разделом реестра.
Предупреждение
Если запрашиваемое значение является строкой (REG_SZ, REG_MULTI_SZ и REG_EXPAND_SZ) возвращаемое значение не гарантируется, что значение будет завершено null. Используйте функцию RegGetValue, если вы хотите убедиться, что возвращаемые строковые значения завершаются значением NULL. Дополнительные сведения см. в приведенных ниже замечаниях.
Синтаксис
LSTATUS RegQueryValueExW(
[in] HKEY hKey,
[in, optional] LPCWSTR lpValueName,
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_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpValueName
Имя значения реестра.
Если lpValueNamenull или пустую строку", функция извлекает тип и данные для неназванного или значения по умолчанию ключа, если таковые имеются.
Если lpValueName указывает значение, которое не находится в реестре, функция возвращает ERROR_FILE_NOT_FOUND.
Ключи не имеют автоматического значения без имени или по умолчанию. Неименованные значения могут иметь любой тип. Дополнительные сведения см. в разделе Ограничения размера элемента реестра.
lpReserved
Этот параметр зарезервирован и должен быть null.
[out, optional] lpType
Указатель на переменную, которая получает код, указывающий тип данных, хранящихся в указанном значении. Список возможных кодов типов см. в типах значений реестра. Параметр lpType может быть NULL, если код типа не требуется.
[out, optional] lpData
Указатель на буфер, получающий данные значения. Этот параметр может быть значение NULL, если данные не требуются.
[in, out, optional] lpcbData
Указатель на переменную, указывающую размер буфера, на который указывает параметр lpData в байтах. При возврате функции эта переменная содержит размер данных, скопированных в lpData.
Параметр lpcbData
Если данные имеют тип REG_SZ, REG_MULTI_SZ или REG_EXPAND_SZ, этот размер включает в себя все null символов или символов, если данные не хранятся без них. Дополнительные сведения см. в разделе "Примечания".
Если буфер, указанный параметром lpData, недостаточно велик для хранения данных, функция возвращает ERROR_MORE_DATA и сохраняет требуемый размер буфера в переменной, на которую указывает lpcbData. В этом случае содержимое буфера lpData не определено.
Если lpData NULL, а lpcbData не являетсяNULL, функция возвращает ERROR_SUCCESS и сохраняет размер данных в байтах в переменной, на которую указывает lpcbData. Это позволяет приложению определить оптимальный способ выделения буфера для данных значения.
Если hKey указывает HKEY_PERFORMANCE_DATA и буфер lpData недостаточно велик, чтобы содержать все возвращаемые данные, RegQueryValueEx возвращает ERROR_MORE_DATA, а значение, возвращаемое через параметр lpcbData, не определено. Это связано с тем, что размер данных производительности может измениться с одного вызова на следующий. В этом случае необходимо увеличить размер буфера и вызвать RegQueryValueEx повторно передать обновленный размер буфера в параметре lpcbData. Повторите это, пока функция не будет успешно выполнена. Для отслеживания размера буфера необходимо сохранить отдельную переменную, так как значение, возвращаемое lpcbData, является непредсказуемым.
Если значение реестра lpValueName не существует, RegQueryValueEx возвращает ERROR_FILE_NOT_FOUND, а значение, возвращаемое lpcbData, не определено.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение ERROR_SUCCESS.
Если функция завершается ошибкой, возвращаемое значение является системным кодом ошибки.
Если буфер lpData слишком мал для получения данных, функция возвращает ERROR_MORE_DATA.
Если значение реестра lpValueName не существует, функция возвращает ERROR_FILE_NOT_FOUND.
Замечания
Приложение обычно вызывает RegEnumValue, чтобы определить имена значений, а затем RegQueryValueEx, чтобы получить данные для имен.
Если данные имеют REG_SZ, REG_MULTI_SZ или тип REG_EXPAND_SZ, строка может не храниться с соответствующими символами null. Таким образом, даже если функция возвращает ERROR_SUCCESS, приложение должно убедиться, что строка будет правильно завершена перед его использованием; в противном случае он может перезаписать буфер. (Обратите внимание, что строки REG_MULTI_SZ должны иметь два конца символов null.) Одним из способов, позволяющих приложению правильно завершить строку, является использование RegGetValue, которая добавляет символы null при необходимости.
Если данные имеют REG_SZ, REG_MULTI_SZ или тип REG_EXPAND_SZ, и используется версия ANSI этой функции (либо путем явного вызова RegQueryValueExA, либо путем определения ЮНИКОДа перед включением файла Windows.h), эта функция преобразует хранимую строку Юникода в строку ANSI перед копированием в буфер, на который указывает lpData.
При вызове функции RegQueryValueEx с hKey задано значение дескриптора HKEY_PERFORMANCE_DATA и строки значений указанного объекта, возвращаемая структура данных иногда имеет нераспоследованные объекты. Не удивляйтесь; это нормальное поведение. При вызове функции RegQueryValueEx всегда следует ожидать, чтобы получить возвращаемую структуру данных для поиска запрошенного объекта.
Обратите внимание, что операции, обращаюющиеся к определенным разделам реестра, перенаправляются. Дополнительные сведения см. в разделе Виртуализация реестра и 32-разрядных и 64-разрядных данных приложений в реестре.
Примеры
Убедитесь, что вы повторно инициализируете значение, указываемое параметром lpcbData при каждом вызове этой функции. Это очень важно при вызове этой функции в цикле, как показано в следующем примере кода.
#include <windows.h>
#include <malloc.h>
#include <stdio.h>
#define TOTALBYTES 8192
#define BYTEINCREMENT 4096
void main()
{
DWORD BufferSize = TOTALBYTES;
DWORD cbData;
DWORD dwRet;
PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
cbData = BufferSize;
printf("\nRetrieving the data...");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
while( dwRet == ERROR_MORE_DATA )
{
// Get a buffer that is big enough.
BufferSize += BYTEINCREMENT;
PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
cbData = BufferSize;
printf(".");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
}
if( dwRet == ERROR_SUCCESS )
printf("\n\nFinal buffer size is %d\n", BufferSize);
else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}
Заметка
Заголовок winreg.h определяет RegQueryValueEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 2000 Профессиональный [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winreg.h (включая Windows.h) |
| библиотеки |
Advapi32.lib |
| DLL | Advapi32.dll |
См. также
Обзор реестра