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

Статья
08/26/2023

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

Синтаксис

LSTATUS SHRegQueryUSValueA(
  [in]                HUSKEY hUSKey,
  [in, optional]      LPCSTR 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, которая содержит имя запрашиваемого значения.

[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. Если задано значение FALSE, 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 Professional, Windows XP [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	shlwapi.h
Библиотека	Shlwapi.lib
DLL	Shlwapi.dll (версия 4.71 или более поздняя)

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