RegReplaceKey

The RegReplaceKey function replaces the file backing a 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,  // address of name of subkey
  LPCTSTR lpNewFile, // address of filename for file with new data
  LPCTSTR lpOldFile  // address of filename for backup file
);
 

Parameters

hKey

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

Pointer to a null-terminated string containing the name of a 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.

The selected key must be the root of a hive; that is, it must be an immediate descendent of HKEY_LOCAL_MACHINE or HKEY_USERS.

lpNewFile

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

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: The calling process must have the SE_RESTORE_NAME privilege. For more information about privileges, see Privileges.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in winreg.h.
  Import Library: Use advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

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