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

Статья
11/20/2024

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

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

Синтаксис

LSTATUS SHRegGetValueW(
  [in]      HKEY    hkey,
  [in]      LPCWSTR pszSubKey,
  [in]      LPCWSTR 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-terminated, указывающую относительный путь от hkey к подразделу, из которого извлекается значение. Этот параметр может быть null или пустую строку, в этом случае данные извлекаются из расположения hkey.

[in] pszValue

Тип: LPCTSTR

Указатель на строку null-terminated, содержащую имя значения. Этот параметр может быть 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 только в том случае, если pvDataNULL. При выходе 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 и гарантированное null-завершение 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 не задан. Следующие условия приводят к дополнительному вызову.

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

Заметка

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

Требования

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

См. также

RegQueryValueEx

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