Функция RegQueryValueExA (winreg.h)
Извлекает тип и данные для указанного имени значения, связанного с открытым разделом реестра.
Предупреждение
Если запрашиваемое значение является строкой (REG_SZ, REG_MULTI_SZ и REG_EXPAND_SZ), возвращаемое значение НЕ гарантируется, что оно будет заканчиваться null. Используйте функцию RegGetValue , если вы хотите убедиться, что возвращаемые строковые значения завершаются null. Дополнительные сведения см. в примечаниях ниже.
Синтаксис
LSTATUS RegQueryValueExA(
[in] HKEY hKey,
[in, optional] LPCSTR 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
Имя значения реестра.
Если lpValueName имеет значение NULL или пустую строку "", функция получает тип и данные для неименованного или значения по умолчанию ключа, если таковое имеется.
Если lpValueName указывает значение, отсутствующее в реестре, функция возвращает ERROR_FILE_NOT_FOUND.
Ключи не имеют автоматически неименованного значения или значения по умолчанию. Неименованные значения могут иметь любой тип. Дополнительные сведения см. в разделе Ограничения размера элементов реестра.
lpReserved
Этот параметр зарезервирован и должен иметь значение NULL.
[out, optional] lpType
Указатель на переменную, которая получает код, указывающий тип данных, хранящихся в указанном значении. Список возможных кодов типов см. в разделе Типы значений реестра. Параметр lpType может иметь значение NULL , если код типа не требуется.
[out, optional] lpData
Указатель на буфер, который получает данные значения. Этот параметр может иметь значение NULL , если данные не требуются.
[in, out, optional] lpcbData
Указатель на переменную, указывающую размер буфера, на который указывает параметр lpData , в байтах. При возврате функции эта переменная содержит размер данных, скопированных в lpData.
Параметр lpcbData может иметь значение NULL , только если lpData имеет значение NULL.
Если данные имеют тип 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 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | winreg.h (включая Windows.h) |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по