Share via

3.1.5.14 BaseRegLoadKey (Opnum 13)

  • Article

The BaseRegLoadKey method is called by the client. In response, the server loads key, subkey, and value data from a file and inserts the data into the registry hierarchy.

The BaseRegLoadKey method is designed for use in backup and recovery scenarios where the client first loads a registry hive from a file on disk using the BaseRegLoadKey method. Then, after reading or writing key data from the loaded hive, the client uses the BaseRegUnLoadKey method to unload the hive. For example, a backup application loads another user hive (another user's HKEY_CURRENT_USER ) from a file on disk using the BaseRegLoadKey method. After reading key and value data, it will unload the hive using the BaseRegUnLoadKey method.

 error_status_t BaseRegLoadKey(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpSubKey,
   [in] PRRP_UNICODE_STRING lpFile
 );

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: OpenUsers and OpenLocalMachine.

Note The other open methods in this protocol cannot be used to obtain the hKey parameter because the server checks that the key specified by lpSubKey is a descendent of the HKEY_LOCAL_MACHINE or HKEY_USERS root keys.

lpSubKey: A pointer to an RRP_UNICODE_STRING structure that specifies the name of the key (as specified in section 3.1.1.1) that MUST be created under hKey.

lpFile: A pointer to a null-terminated RRP_UNICODE_STRING structure that contains the name of an existing registry file in which the specified key and subkeys are to be saved. The format of the file name is implementation-specific. It is assumed that this file was created with the BaseRegSaveKey method. If it does not exist, the server creates a file with the specified name.

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.

0x000003F9

ERROR_NOT_REGISTRY_FILE

The system attempted to load or restore a file into the registry, but the specified file is not in a registry file format.

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

In response to this request from the client, for a successful operation, the server MUST create a hierarchical structure of a key, subkeys, and values that are based on the layout and information in the file that is specified by the lpFile parameter. See section 3.1.1. This tree MUST be rooted at the key that is specified by the lpSubKey parameter.

If the subkey that is specified by the lpSubKey parameter does not exist under the key that is specified by the hKey parameter, the server creates a subkey under hKey by using the name that is specified in the lpSubKey parameter and loads the registry information from the file that is specified by lpFile into this subkey. If the file that is pointed to by lpFile does not exist, the server creates the file with the specified name. If the file cannot be created, the server fails the operation by using an appropriate error code, as specified in section 2.2.6.

If the subkey that is specified by the lpSubKey parameter already exists under the key that is specified by the hKey parameter, the server MUST fail the method and return ERROR_ACCESS_DENIED.

The top-level key from the file that is specified by the lpFile parameter is a newly created key, and it is added as a subkey to the key specified by the hKey parameter. If the lpSubKey parameter is NULL, then the name of the top-level key from the file specified by the lpFile parameter is the name of the newly created key. If the lpSubKey parameter is not NULL, then the name of the newly created key is set to be the name specified by the lpSubKey parameter.

If the value of the lpFile parameter is NULL, the server MUST fail the method and return ERROR_INVALID_PARAMETER.

The file that is pointed to by the lpFile parameter MUST be a valid registry file. If not, the server MUST return ERROR_NOT_REGISTRY_FILE (1017) to indicate the format of the file was invalid. If the file pointed to by lpFile cannot be found, the server creates a file with the specified name.

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.

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