3.1.5.18 BaseRegReplaceKey (Opnum 18)

  • Article

The BaseRegReplaceKey method is called by the client. In response, the server MUST read the registry information from the specified file and replace the specified key with the content of the file. When the system is started again, the key and subkeys have the same values as those in the specified file.

 error_status_t BaseRegReplaceKey(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpSubKey,
   [in] PRRP_UNICODE_STRING lpNewFile,
   [in] PRRP_UNICODE_STRING lpOldFile
 );

hKey: A handle to a key that MUST have been opened previously by using one of the open methods that are specified in section 3.1.5: OpenClassesRoot, OpenCurrentUser, OpenLocalMachine, OpenPerformanceData, OpenUsers, BaseRegCreateKey, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

lpSubKey: A pointer to an RRP_UNICODE_STRING structure that MUST either contain the name of the key whose subkeys and values are replaced by this method (as specified in section 3.1.1), or be NULL.

lpNewFile: A pointer to an RRP_UNICODE_STRING structure that MUST contain a registry file name with the registration information, as specified in section 3.1.1. The format of the file name is implementation-specific, but both lpNewFile and lpOldFile SHOULD<22> be in the same format.

lpOldFile: A pointer to an RRP_UNICODE_STRING structure that MUST contain the registry file name that receives a backup copy of the replaced registry information. The format of the file name is implementation-specific, but is in the same format as lpNewFile.

Return Values: The method returns 0 (ERROR_SUCCESS) to indicate success; otherwise, it returns a nonzero error code, as specified in [MS-ERREF] section 2.2. The most common error codes are listed in the following table.

Return value/code

Description

0x00000057

ERROR_INVALID_PARAMETER

A parameter is incorrect.

0x00000013

ERROR_WRITE_PROTECT

A read or write operation was attempted to a volume after it was dismounted. The server can no longer service registry requests because server shutdown has been initiated.

0x00000011

ERROR_NOT_SAME_DEVICE

The file indicated by lpOldFile is not on the same physical volume as the file indicated by lpNewFile.

Server Operations

The server MUST delete the subkeys and values specified by lpSubKey even if the subkeys to be deleted are already in use and initialized in the Data Store before the deletion happens. The delete function will be successful even if other handles are open to the key. The data inside the hive is revoked at delete key time and is not deferred until the last handle close operation.

The file specified by the BaseRegReplaceKey method is used as a registry hive, and its contents are loaded into the registry, replacing the existing key and subkeys. The top-level key of the file replaces the key specified in the method.

If the registry server can no longer service registry requests because server shutdown has been initiated (SHUTDOWNINPROGRESS is set to TRUE), the server MUST return ERROR_WRITE_PROTECT.

In response to this request from the client, for a successful operation, the server MUST replace the file that backs up the specified registry key and all its subkeys with another file.

The key that is specified by lpSubKey in the request MUST be a subkey of the key that is identified by the hKey parameter. If the specified key is not the root of the tree, the server MUST traverse up the tree structure until it encounters the root. After the root is found, the server MUST replace the resulting contents of that traversal (starting at the root) by using the contents of the backing store that is specified by lpNewFile, which results in the root key specified in lpNewFile becoming the new root of the hive. (For instance in a hive with Red->White->Blue, if White is the lpSubKey parameter, and the backing store contains Alpha->Beta->Gamma, the server MUST first traverse up to the root of the hive Red and then replace that with Alpha->Beta->Gamma).

If lpSubKey is NULL, the server MUST replace the file that is backing up the hKey parameter. Changes to the registry information take effect after restarting the computer.

If the file indicated by lpNewFile does not exist, the server MUST fail the method and return ERROR_FILE_NOT_FOUND.

If the file that receives the backup copy of the replaced registry information indicated by lpOldFile already exists, the server MUST fail the method and return ERROR_ALREADY_EXISTS.

The server MUST store a backup copy of the replaced registry information in the file that is pointed to by the lpOldFile parameter.

The server SHOULD<23> check for a location relationship between the files to protect against malicious or accidental change while in use, and to ensure ready access.

The server MUST return 0 to indicate success, or an appropriate error code (as specified in [MS-ERREF]) to indicate an error.

If any of the parameters lpNewFile, lpOldFile, or lpSubKey are NULL or reference a buffer that is NULL, the server MUST return ERROR_INVALID_PARAMETER.