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

Статья
11/20/2024

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

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

Синтаксис

LSTATUS RegRestoreKeyA(
  [in] HKEY   hKey,
  [in] LPCSTR lpFile,
  [in] DWORD  dwFlags
);

Параметры

[in] hKey

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

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS Все сведения, содержащиеся в этом ключе, и его ключи-потомки перезаписываются информацией в файле, на которую указывает параметр lpFile.

[in] lpFile

Имя файла с сведениями реестра. Этот файл обычно создается с помощью функции RegSaveKey.

[in] dwFlags

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

Ценность	Значение
REG_FORCE_RESTORE 0x000000008L	Если задано, операция восстановления выполняется даже в том случае, если открытые дескрипторы существуют в иерархии реестра или под ним, к которым указывает hKey параметров.
REG_WHOLE_HIVE_VOLATILE 0x000000001L	При указании создается новый, изменяющийся (только для памяти) набор сведений о реестре или hive. Если указан REG_WHOLE_HIVE_VOLATILE, ключ, определенный параметром hKey, должен быть значением HKEY_USERS или HKEY_LOCAL_MACHINE.

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

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

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

Замечания

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

Если открыты какие-либо подразделы параметра hKey, RegRestoreKey завершается ошибкой.

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

Эта функция заменяет ключи и значения ниже указанного ключа ключами и значениями, которые являются дочерними ключами верхнего уровня в файле, независимо от имени ключа верхнего уровня в файле. Например, hKey может определить ключ A с вложенными ключами B и C, а параметр lpFile указывает файл, содержащий ключ X с вложенными ключами Y и Z. После вызова RegRestoreKeyреестр будет содержать раздел A с вложенными ключами Y и Z. Записи значений A будут заменены записями значений X.

Новые сведения в файле, указанном lpFile перезаписывает содержимое ключа, указанного параметром hKey, за исключением имени ключа.

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

Заметка

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

Требования

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