3.1.5.6 BaseRegCloseKey (Opnum 5)

The BaseRegCloseKey method is called by the client. In response, the server destroys (closes) the handle to the specified registry key.

 error_status_t BaseRegCloseKey(
   [in, out] PRPC_HKEY hKey
 );

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.

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
0x00000006 ERROR_INVALID_HANDLE	The handle is invalid.
0x000000AA ERROR_BUSY	The requested resource is in use.
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.
0x00000015 ERROR_NOT_READY	The service is not read. Calls can be repeated at a later time.
0x00000102 WAIT_TIMEOUT	The wait operation timed out.

Server Operations

If the registry server can no longer service registry requests because server shutdown has been initiated, the server MUST return ERROR_WRITE_PROTECT.

If the handle provided in the hKey parameter is not a valid open handle to a registry key, the server MUST fail the method and return ERROR_INVALID_HANDLE. If the operation was unsuccessful, the server MUST NOT change the value of the hKey parameter and return the original value to the client.

If the registry server cannot obtain a lock on a registry request, the server MUST return ERROR_BUSY. The operation SHOULD be repeated.

The server MUST determine if the UPDATECOPY column of the entry for hKey in the HANDLETABLE is set to true. If UPDATECOPY is set to true, the server MUST copy all subkeys and values of the key indicated by the hKey parameter from the 32-bit key namespace into the 64-bit key namespace or from the 64-bit key namespace into the 32-bit key namespace. Any values already in the target namespace are overwritten as part of the copy operation. Any errors encountered during the copy operation are not returned to the client, and the result of the copy operation is undefined.

In response to this request from the client, for a successful operation, the server MUST return 0 to indicate success and close the handle to the key that is specified by the hKey parameter in the client request. The server MUST also set the value of the hKey parameter to NULL. The server MUST also remove the entry for hKey in the HANDLETABLE.

The implementation of the handle close operation is server-specific. However, functionally, after a handle is closed, the server MUST not allow the handle to refer to a given registry key until a new handle is created and opened for that key using one of the open methods that are specified in section 3.1.5: OpenClassesRoot, OpenCurrentUser, OpenLocalMachine, OpenPerformanceData, OpenUsers, BaseRegCreateKey, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

If the method is unsuccessful, the server MUST return a nonzero error code, as specified in [MS-ERREF] section 2.2.

The server MUST return ERROR_BUSY if an internal lock cannot be obtained. This would happen under very high contention rates or if the client is corrupted. The operation SHOULD be repeated.

The server returns WAIT_TIMEOUT if the server load is high and it is unable to acquire locks on the registry database.