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

Статья
11/20/2024

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

Синтаксис

LSTATUS SHRegGetUSValueA(
  [in]                LPCSTR pszSubKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out, optional] DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in]                DWORD  dwDefaultDataSize
);

Параметры

[in] pszSubKey

Тип: LPCTSTR

Указатель на строку, завершаемую значением NULL, с именем подраздела относительно HKEY_LOCAL_MACHINE и HKEY_CURRENT_USER. Например: Software\MyCompany\MyProduct.

[in, optional] pszValue

Тип: LPCTSTR

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

[in, out, optional] pdwType

Тип: DWORD*

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

[out, optional] pvData

Тип: void*

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

[in, out, optional] pcbData

Тип: DWORD*

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

[in] fIgnoreHKCU

Тип: BOOL

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

[in, optional] pvDefaultData

Тип: void*

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

[in] dwDefaultDataSize

Тип: DWORD

Длина буфера в байтах, на которую указывает pvDefaultData.

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

Тип: LSTATUS

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

Замечания

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

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

Заметка

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

Требования

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

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