Поделиться через

Функция SHRegGetValueA (shlwapi.h)

  • Статья

[SHRegGetValue может быть изменено или недоступно в последующих версиях операционной системы или продукта. Вместо нее используйте RegGetValue .]

Извлекает значение реестра.

Синтаксис

LSTATUS SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR pszValue,
  [in]      SRRF   srrfFlags,
  [in, out] DWORD  *pdwType,
  [out]     void   *pvData,
  [in, out] DWORD  *pcbData
);

Параметры

[in] hkey

Тип: HKEY

Дескриптор открытого ключа или любое из следующих предопределенных значений.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

Тип: LPCTSTR

Указатель на строку, завершающуюся null, которая указывает относительный путь от hkey к подразделу, из которого извлекается значение. Этот параметр может иметь значение NULL или пустую строку. В этом случае данные извлекаются из расположения hkey .

[in] pszValue

Тип: LPCTSTR

Указатель на строку, завершающуюся значением NULL, которая содержит имя значения. Этот параметр может иметь значение NULL или пустую строку. В этом случае данные извлекаются из значения по умолчанию.

[in] srrfFlags

Тип: SRRF

Один или несколько флагов SRRF , ограничивающих извлечение данных. Необходимо указать по крайней мере одно значение ограничения типа (SRRF_RT).

[in, out] pdwType

Тип: LPDWORD

Указатель на DWORD , который получает тип данных, хранящихся в полученном значении. При использовании значений по умолчанию входной pdwType является типом значения по умолчанию. Возможные значения см. в разделе Типы данных реестра. Если флаг SRRF_NOEXPAND не задан, REG_EXPAND_SZ типы автоматически разворачиваются и возвращаются как REG_SZ. Если сведения о типе не требуются, этот параметр может иметь значение NULL.

[out] pvData

Тип: LPVOID

Указатель на буфер, который получает данные значения. Этот параметр может иметь значение NULL , если данные не требуются. Например, если вы проверяли только существование значения, данные конкретного значения были бы лишними.

[in, out] pcbData

Тип: LPDWORD

Указатель на DWORD , который в записи содержит размер буфера данных назначения pvData в байтах. Это значение может иметь значение NULL , только если pvData имеет значение NULL. При выходе pcbData указывает на одно из этих значений.

pvData Возвращаемое значение pcbData
NULL ERROR_SUCCESS Размер в байтах, достаточный для хранения данных реестра. Обратите внимание, что это не гарантируется точный размер, а только достаточный размер.
Отличное от NULL ERROR_SUCCESS Точное число байтов, записанных в pvData.
Отличное от NULL ERROR_MORE_DATA Размер в байтах, необходимый для хранения всех данных. Обратите внимание, что это не гарантируется точный размер, а только достаточный размер.

Возвращаемое значение

Тип: LSTATUS

Возвращает ERROR_SUCCESS в случае успешного выполнения, или ненулевой код ошибки, определенный в Winerror.h, в противном случае. Чтобы получить общее описание ошибки, можно использовать функцию FormatMessage с флагом FORMAT_MESSAGE_FROM_SYSTEM .

Комментарии

SHRegGetValue обеспечивает проверку типов данных, проверку режима загрузки, автоматическое расширение данных REG_EXPAND_SZ и гарантированное завершение REG_SZ, REG_EXPAND_SZ и REG_MULTI_SZ данных с пустым значением.

Ключ, определяемый ключом hkey , должен быть открыт с KEY_QUERY_VALUE доступа по безопасности. Если pszSubKey не имеет значение NULL или пустую строку, этот ключ также должен быть открыт с KEY_QUERY_VALUE доступа по безопасности в текущем контексте вызова.

Если тип данных является REG_SZ, REG_EXPAND_SZ или REG_MULTI_SZ, то все возвращаемые данные включают или учитывают завершение строки со значением NULL. Например, если pvData не равно NULL, данные, возвращаемые в этом буфере, завершаются null. Если pcbData не равно NULL, размер буфера, на который он указывает, включает байты, необходимые для хранения завершающего символа NULL .

Если флаг SRRF_NOEXPAND не установлен, строковые данные типа REG_EXPAND_SZ автоматически разворачиваются перед возвратом. Тип развернутой строки указывается в pdwType как REG_SZ, параметр pcbData указывает на количество байтов, записанных для развернутой строки, а буфер, на который указывает pvData , содержит расширенную версию строки.

Заметки о производительности

Если pszSubKey не имеет значение NULL или пустая строка, этот ключ открывается и закрывается этой функцией при каждом обращении к ней. Если приложение должно получить ряд значений из того же подраздела, вы увидите лучшую производительность, открыв ключ с помощью RegOpenKeyEx перед вызовом SHRegGetValue. Используйте ключ, возвращенный в параметре phkResultregOpenKeyEx , в качестве параметра hkey в этой функции, а для параметра pszSubKey задано значение NULL.

Возможность дополнительного вызова реестра для чтения или повторного чтения данных существует, если тип данных REG_EXPAND_SZ и флаг SRRF_NOEXPAND не задан. Следующие условия приводят к такому дополнительному вызову.

  • pvData имеет значение NULL, pcbData — не NULL. Хотя данные не извлекаются, реестр должен быть прочитан, чтобы получить строку, и эта строка развернута, чтобы определить необходимый размер буфера данных.
  • Значение pvData не равно NULL, но слишком мало для хранения данных. Данные повторно считываются, чтобы получить полную строку, строка разворачивается и определяется общий необходимый размер.

Примечание

Заголовок shlwapi.h определяет SHRegGetValue в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows XP с пакетом обновления 2 (SP2) [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header shlwapi.h
Библиотека Shlwapi.lib
DLL Shlwapi.dll (версия 6.0 или более поздняя)

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

RegQueryValueEx