Функция RegSetValueExA (winreg.h)

Статья
11/20/2024

Задает данные и тип указанного значения в разделе реестра.

Синтаксис

LSTATUS RegSetValueExA(
  [in]           HKEY       hKey,
  [in, optional] LPCSTR     lpValueName,
                 DWORD      Reserved,
  [in]           DWORD      dwType,
  [in]           const BYTE *lpData,
  [in]           DWORD      cbData
);

Параметры

[in] hKey

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

Этот дескриптор возвращается RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExили функцией RegOpenKeyTransacted. Он также может быть одним из следующих предопределенных ключей:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

Версия этой функции Юникода поддерживает следующие дополнительные стандартные ключи:

HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT

[in, optional] lpValueName

Имя заданного значения. Если значение с этим именем еще не присутствует в ключе, функция добавляет ее в ключ.

Если lpValueNamenull или пустую строку", функция задает тип и данные для неназванного или значения по умолчанию ключа.

Дополнительные сведения см. в разделе Ограничения размера элемента реестра.

Разделы реестра не имеют значений по умолчанию, но они могут иметь одно неназванное значение, которое может быть любого типа.

Reserved

Этот параметр зарезервирован и должен быть нулевым.

[in] dwType

Тип данных, на который указывает параметр lpData. Список возможных типов см. в типах значений реестра.

[in] lpData

Хранимые данные.

Для строковых типов, таких как REG_SZ, строка должна быть null-terminated. При использовании типа данных REG_MULTI_SZ строка должна быть завершена двумя символами null.

Примечание lpData, указывающее, что значение null допустимо, однако если это так, cbData должно иметь значение 0.

[in] cbData

Размер информации, на которую указывает параметр lpData в байтах. Если данные имеют тип REG_SZ, REG_EXPAND_SZ или REG_MULTI_SZ, cbData должны содержать размер конца символов или символов null.

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

Если функция выполнена успешно, возвращаемое значение ERROR_SUCCESS.

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

Замечания

Размеры значений ограничены доступной памятью. Однако хранение больших значений в реестре может повлиять на его производительность. Длинные значения (более 2 048 байт) должны храниться в виде файлов с расположениями файлов, хранящихся в реестре.

Такие элементы приложения, как значки, растровые изображения и исполняемые файлы, должны храниться в виде файлов и не помещаться в реестр.

Если dwType является типом REG_SZ, REG_MULTI_SZ или REG_EXPAND_SZ и используется версия ANSI этой функции (путем явного вызова RegSetValueExA или без определения ЮНИКОДа перед включением файла Windows.h), данные, на которые указывает параметр lpData, должны быть строкой символов ANSI. Строка преобразуется в Юникод, прежде чем она хранится в реестре.

Обратите внимание, что операции, обращаюющиеся к определенным разделам реестра, перенаправляются. Дополнительные сведения см. в разделе Виртуализация реестра и 32-разрядных и 64-разрядных данных приложений в реестре.

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

Заметка

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

Требования

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