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

Статья
11/20/2024

Извлекает тип и данные для указанного имени, связанного с открытым подразделом реестра, в поддереве конкретного пользователя (HKEY_CURRENT_USER или HKEY_LOCAL_MACHINE).

Синтаксис

LSTATUS SHRegQueryUSValueW(
  [in]                HUSKEY  hUSKey,
  [in, optional]      LPCWSTR pszValue,
  [in, out, optional] DWORD   *pdwType,
  [out, optional]     void    *pvData,
  [in, out]           DWORD   *pcbData,
  [in]                BOOL    fIgnoreHKCU,
  [in, optional]      void    *pvDefaultData,
  [in, optional]      DWORD   dwDefaultDataSize
);

Параметры

[in] hUSKey

Тип: HUSKEY

Дескриптор открытого подраздела реестра или одного из следующих предопределенных значений. Вложенный ключ должен быть открыт с помощью права доступа KEY_SET_VALUE. Дополнительные сведения см. в разделе "Безопасность и права доступа реестра".

Этот дескриптор можно получить с помощью функции SHRegOpenUSKey.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in, optional] pszValue

Тип: LPCTSTR

Указатель на строку null-terminated, содержащую имя запрашиваемого значения.

[in, out, optional] pdwType

Тип: LPDWORD*

Указатель на переменную, которая задает или получает тип значения ключа. Дополнительные сведения см. в типах данных реестра. Этот параметр может быть NULL.

[out, optional] pvData

Тип: LPVOID*

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

[in, out] pcbData

Тип: LPDWORD*

Указатель на переменную, указывающую размер буфера в байтах, на который указывает параметр pvData. Когда функция возвращается, эта переменная содержит размер скопированных данных в pvData.

[in] fIgnoreHKCU

Тип: BOOL

Переменная, указывающая, какой ключ следует просмотреть. Если задано значение TRUE, SHRegQueryUSValue игнорирует HKEY_CURRENT_USER и возвращает значение из ключа в HKEY_LOCAL_MACHINE.

[in, optional] pvDefaultData

Тип: LPVOID*

Указатель на данные по умолчанию.

[in, optional] dwDefaultDataSize

Тип: DWORD

Длина данных по умолчанию в байтах.

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

Тип: LSTATUS

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

Замечания

Если fIgnoreHKCU установлено значение TRUE, SHRegQueryUSValue возвращает значение из ключа в HKEY_LOCAL_MACHINE. Если задано значение falseFALSE, SHRegQueryUSValue сначала пытается вернуть значение из ключа в HKEY_CURRENT_USER. Однако если ключ не найден в HKEY_CURRENT_USER, значение возвращается из ключа в HKEY_LOCAL_MACHINE. Если ни ключ отсутствует, либо возникает ошибка и dwDefaultDataSize ненулевое, данные по умолчанию копируются в pvData и возвращаются ERROR_SUCCESS. ERROR_SUCCESS возвращается как для данных по умолчанию, так и не по умолчанию, и нет способа различать, какие значения копируются в pvData. Чтобы предотвратить использование данных по умолчанию, задайте pvDefaultData значение NULL и dwDefaultDataSize равным нулю.

Если требуется только прочитать одно значение, SHRegGetUSValue откроет ключ и возвращает значение. Чтобы использовать SHRegQueryUSValue, необходимо сначала открыть ключ с SHRegOpenUSKey. Однако после открытия ключа можно использовать SHRegQueryUSValue столько раз, сколько необходимо. Если требуется получить несколько значений из одного ключа, использование нескольких вызовов SHRegQueryUSValue обычно эффективнее, чем SHRegGetUSValue, так как ключ открыт только один раз.

Заметка

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

Требования

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

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