Функция SHRegQueryUSValueA (shlwapi.h)
Извлекает тип и данные для указанного имени, связанного с открытым подразделом реестра в пользовательском поддереве (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 или более поздняя) |