3.1.4.2.31 ApiOpenKey (Opnum 30)

(Protocol Version 3) In response to the ApiOpenKey method, for a successful operation, the server MUST open the key in the cluster registry that is specified by lpSubKey.

The server MUST evaluate the security descriptor that is associated with the key against the user authorization context and requested access as expressed in the samDesired parameter in order to determine whether the caller can open this key.

The server SHOULD accept an ApiOpenKey request if its protocol server state is read-only and MUST accept the request for processing if it is in the read/write state, as specified in section 3.1.1.

The server SHOULD accept an ApiOpenKey request if the client's access level is at least "Read" (section 3.1.4).

 HKEY_RPC ApiOpenKey(
   [in] HKEY_RPC hKey,
   [in, string] LPCWSTR lpSubKey,
   [in] DWORD samDesired,
   [out] error_status_t *Status,
   [out] error_status_t *rpc_status
 );

hKey: The RPC context handle for a key that was previously obtained by a call to ApiGetRootKey, ApiCreateKey, or ApiOpenKey.

lpSubKey: A null-terminated Unicode string that specifies the name of the subkey to be opened. The lpSubKey parameter MUST indicate a subkey that is a child of the key that is identified by hKey; does not begin with the "\" character; and is not NULL. The lpSubKey parameter can be an empty string, in which case the server MUST return an HKEY_RPC context handle that represents the cluster registry key that is represented by hKey.

samDesired: The bitmask that indicates the requested level of access to the subkey. The values in the bitmask are as specified in [MS-RRP] for REGSAM.

Status: Indicates the status of this operation. The server MUST set Status to the following error codes for the specified conditions.

Value	Meaning
ERROR_SUCCESS 0x00000000	Success.
ERROR_ACCESS_DENIED 0x00000005	The client is not permitted to open the specified subkey with the requested access.
ERROR_INVALID_HANDLE 0x00000006	The hKey value does not indicate a valid cluster registry key.

For any other condition, the server MUST set Status to a value that is not one of the values listed in the preceding table. The client MUST treat all values that are not listed in the preceding table the same, except as specified in section 3.2.4.6.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether it succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for  comm_status and fault_status, as specified in Appendix E of [C706].

Return Values: If the method succeeds, the server MUST return a valid HKEY_RPC context handle; otherwise, the server MUST return NULL.