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

Статья
08/27/2023

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

Синтаксис

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

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

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

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

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

Reserved

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

[in] dwType

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

[in] lpData

Сохраняемые данные.

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

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

[in] cbData

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

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

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

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

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

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

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

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

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

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winreg.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll