3.1.5.23 BaseRegUnLoadKey (Opnum 23)

The BaseRegUnLoadKey method is called by the client. In response, the server removes the specified discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

The BaseRegUnLoadKey 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 can load another user hive (another user's HKEY_CURRENT_USER) from a file on disk using the BaseRegLoadKey method. Then, after reading key and value data, it will unload the hive using the BaseRegUnLoadKey method.

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

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

lpSubKey: An optional pointer to an RRP_UNICODE_STRING structure that MUST contain the relative name, as specified in section 3.1.1.1.2. The lpSubKey parameter points to the name of the key that is to be unloaded.

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.
0x00000002 ERROR_FILE_NOT_FOUND	The key specified by the handle hKey and the lpSubKey parameter does not exist in the key namespace.
0x00000005 ERROR_ACCESS_DENIED	The key specified by the handle hKey and the lpSubKey parameter is not a descendent key of the HKEY_LOCAL_MACHINE or HKEY_USERS root keys, or there are open handles to the key or its descendants.

Server Operations

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, the server MUST logically delete the subtree that is specified by the lpSubKey parameter in the request. If this parameter is NULL, the server MUST logically delete the subtree that is specified by the hKey parameter. Logically deleting a subtree removes it from memory but MUST NOT modify the file that backs up the subtree. A subtree consists of the specified key and all its child keys that are hierarchically below it.

The server MUST validate that the key specified by the handle hKey and the lpSubKey parameter can be unloaded. To be unloaded, the key specified by the handle hKey and the lpSubKey parameter MUST be a descendent key of the HKEY_LOCAL_MACHINE or HKEY_USERS root keys, MUST exist in the key namespace, and there MUST not be any open handles to the key or its descendants.

If the key does not exist in the key namespace, the server MUST return ERROR_FILE_NOT_FOUND.

If there are any open handles to the key or its descendants, the server MUST return ERROR_ACCESS_DENIED.

If the key cannot be unloaded because the key is not a descendent key of the HKEY_LOCAL_MACHINE or HKEY_USERS root keys, the server MUST return ERROR_ACCESS_DENIED.

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

If the lpSubKey parameter is greater than zero and the buffer is NULL, the server MUST return ERROR_INVALID_PARAMETER.