3.1.5.8 BaseRegDeleteKey (Opnum 7)

The BaseRegDeleteKey method is called by the client. In response, the server deletes the specified subkey.

 error_status_t BaseRegDeleteKey(
   [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: OpenClassesRoot, OpenCurrentUser, OpenLocalMachine, OpenPerformanceData, OpenUsers, BaseRegCreateKey, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

lpSubKey: A pointer to an RRP_UNICODE_STRING structure that MUST contain the name of the key (as specified in section 3.1.1) to delete.

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.
0x00000005 ERROR_ACCESS_DENIED	Access is denied. For BaseRegDeleteKey, this error will be returned when the key indicated by the lpSubKey parameter has subkeys.
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 the client request, for a successful operation, the server MUST delete the registry key specified by the lpSubKey parameter in the client request and MUST return 0 (ERROR_SUCCESS). The server MUST delete all data associated with the registry key indicated by the lpSubKey parameter, including the key, any values, and the security descriptor associated with the key.

The server MUST delete the registry key even if the subkey to be deleted is 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.

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 first validates that the hKey parameter is currently an open handle that MUST have been opened previously using one of the methods that are specified in section 3.1.5. If the hKey parameter is not an already open handle, the server MUST return ERROR_INVALID_PARAMETER.

The server then validates that the key specified by the lpSubKey parameter is a subkey of the key indicated by the hKey parameter. If the key specified by the lpSubKey parameter is not a subkey of the key indicated by the hKey parameter, the server MUST return ERROR_FILE_NOT_FOUND.

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

The server then validates that the key indicated by lpSubKey does not have subkeys of its own. If the key indicated by the lpSubKey parameter does have subkeys, the server MUST return ERROR_ACCESS_DENIED.

If both the hKey and lpSubKey parameters are valid and the key indicated by lpSubKey does not have any subkeys, the server MUST return ERROR_SUCCESS and delete the key indicated by lpSubKey, its security descriptor, and any values.