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

Статья
06/01/2023

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

Предупреждение

Если запрашиваемое значение является строкой (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.

Если данные имеют тип 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