RegReplaceKey

The RegReplaceKey function replaces the file backing a registry key and all its subkeys with another file, so that when the system is next started, the key and subkeys will have the values stored in the new file.

LONG RegReplaceKey(
  HKEY hKey,         // handle to open key
  LPCTSTR lpSubKey,  // subkey name
  LPCTSTR lpNewFile, // data file
  LPCTSTR lpOldFile  // backup file
);

Parameters

hKey

[in] Handle to a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

[in] Pointer to a null-terminated string containing the name of the key whose subkeys and values are replaced by this function. This key must be a subkey of the key identified by the hKey parameter. This parameter can be NULL.

If the specified subkey is not the root of a hive, RegReplaceKey traverses up the hive tree structure until it encounters a hive root, then it replaces the contents of that hive with the contents of the data file specified by lpNewFile.

lpNewFile

[in] Pointer to a null-terminated string containing the name of the file with registration information. This file is typically created by using the RegSaveKey function.

lpOldFile

[in] Pointer to a null-terminated string containing the name of a file that receives a backup copy of the registry information being replaced.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in Winerror.h. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

The file specified by the lpNewFile parameter remains open until the system is restarted.

If hKey is a handle returned by RegConnectRegistry, then the paths specified in lpNewFile and lpOldFile are relative to the remote computer.

Windows NT/2000: The calling process must have the SE_RESTORE_NAME privilege. For more information about privileges, see Privileges.

Windows 95/98: No registry subkey or value name may exceed 255 characters.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winreg.h; include Windows.h.
  Library: Use Advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Registry Overview, Registry Functions, RegConnectRegistry, RegDeleteKey, RegLoadKey, RegRestoreKey, RegSaveKey