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

Статья
11/20/2024

Сохраняет указанный ключ и все его подразделы и значения в файле реестра в указанном формате.

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

Синтаксис

LSTATUS RegSaveKeyExA(
  [in]           HKEY                        hKey,
  [in]           LPCSTR                      lpFile,
  [in, optional] const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                       Flags
);

Параметры

[in] hKey

Дескриптор открытого раздела реестра.

Эта функция не поддерживает предварительно определенный ключ HKEY_CLASSES_ROOT.

[in] lpFile

Имя файла, в котором необходимо сохранить указанный ключ и вложенные ключи. Если файл уже существует, функция завершается ошибкой.

Новый файл имеет атрибут архива.

Если строка не содержит путь, файл создается в текущем каталоге вызывающего процесса для локального ключа или %systemroot%в каталоге \system32 для удаленного ключа.

[in, optional] lpSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES, указывающую дескриптор безопасности для нового файла. Если lpSecurityAttributesNULL, файл получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для файла наследуются от родительского каталога.

[in] Flags

Формат сохраненного ключа или hive. Этот параметр может быть одним из следующих значений.

Ценность	Значение
REG_STANDARD_FORMAT 1	Ключ или hive сохраняется в стандартном формате. Стандартный формат — единственный формат, поддерживаемый Windows 2000.
REG_LATEST_FORMAT 2	Ключ или hive сохраняется в последнем формате. Последний формат поддерживается начиная с Windows XP. После сохранения ключа или куста в этом формате его нельзя загрузить в более раннюю систему.
REG_NO_COMPRESSION 4	Hive сохраняется без сжатия для ускорения операций сохранения. Параметр hKey должен указать корень куста в HKEY_LOCAL_MACHINE или HKEY_USERS. Например, HKLM\SOFTWARE является корнем куста.

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

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

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

Если несколько возможных значений, перечисленных выше для параметра Flags, указывается в одном вызове этой функции( например, если задано два или более значений или более, или если задано REG_NO_COMPRESSION и hKey указывает ключ, который не является корнем куста, эта функция возвращает ERROR_INVALID_PARAMETER.

Замечания

В отличие от RegSaveKey, эта функция не поддерживает предварительно определенный ключ HKEY_CLASSES_ROOT.

Если hKey представляет ключ на удаленном компьютере, то путь, описанный lpFile, относится к удаленному компьютеру.

Функция RegSaveKeyEx сохраняет только нелатильные ключи. Он не сохраняет переменные ключи. Ключ делается переменным или неразрешимым при его создании; см. RegCreateKeyEx.

Вы можете использовать файл, созданный RegSaveKeyEx в последующих вызовах функции RegLoadKey, RegReplaceKeyили RegRestoreKey. Если RegSaveKeyEx завершает работу, файл будет поврежден и последующие вызовы RegLoadKey, RegReplaceKeyили RegRestoreKey для файла завершится ошибкой.

Использование RegSaveKeyEx вместе с RegRestoreKey для копирования поддерев в реестре не рекомендуется. Этот метод не активирует уведомления и может отменять дескриптор, используемый другими приложениями. Вместо этого используйте функцию SHCopyKey или функцию RegCopyTree.

В процессе вызова должна быть включена SE_BACKUP_NAME привилегия. Дополнительные сведения см. в разделе Выполнение с специальными привилегиями.

Заметка

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

Требования

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