3.1.5.19 BaseRegRestoreKey (Opnum 19)

The BaseRegRestoreKey method is called by the client. In response, the server reads the registry information in a specified file and copies it over the specified key. The registry information takes the form of a key and multiple levels of subkeys.

 error_status_t BaseRegRestoreKey(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpFile,
   [in] DWORD Flags
 );

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.

lpFile: A pointer to an RRP_UNICODE_STRING structure that contains an existing registry file name. The format of the file name SHOULD<24> be implementation-specific.

Flags: An optional flag argument that is the bitwise OR of any of the following options.

Value	Meaning
REG_WHOLE_HIVE_VOLATILE 0x00000001	If set, registry keys created in the Data Store from the file indicated by lpFile MUST be VOLATILE.
REG_REFRESH_HIVE 0x00000002	If set, the location of the subtree that the hKey parameter points to is restored to its state immediately following the last flush. The subtree MUST NOT be lazy flushed (by calling BaseRegRestoreKey with REG_NO_LAZY_FLUSH specified as the value of this parameter); the caller MUST be a member of the Administrators Group; and the handle the hKey parameter refers to MUST point to the root of the subtree.
REG_NO_LAZY_FLUSH 0x00000004	If set, the key or subtree that is specified by the hKey parameter does not automatically flush at regular intervals of time. The server MUST set the property KEYNOPERIODICFLUSH equal to TRUE for the key specified by the hKey parameter and all subkeys (see section 3.1.1.3).
REG_FORCE_RESTORE 0x00000008	If set, the restore operation is executed even if open handles exist at (or beneath) the location in the registry hierarchy to which the hKey parameter points.<25>

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.

Server Operations

The file specified by the BaseRegRestoreKey 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 read the registry information from the specified file and copy it over the specified key.

If the HANDLETABLE contains an hKey for the key specified by the hKey parameter or any of its subkeys, the server MUST fail the method and return ERROR_ACCESS_DENIED.

If the Flags parameter in the request contains the value 0x00000001, the server MUST create a volatile view (changes are not saved to the backing store) of the registry tree.

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

If the parameter lpFile is NULL or references a buffer that is NULL, then the server MUST return ERROR_INVALID_PARAMETER.

If the parameter lpFile does not contain a valid file name, then the server MUST return ERROR_INVALID_PARAMETER.

If the parameter lpFile references a registry file that does not exist, the server MUST return ERROR_FILE_NOT_FOUND.