3.1.4.1.29 ApiGetRootKey (Opnum 28)

(Protocol Version 2) In response to the ApiGetRootKey method, the server returns an HKEY_RPC context handle that represents the root key of the cluster registry. The server MUST evaluate the security descriptor that is associated with the key against the user authorization context and the requested access that is expressed in the samDesired parameter in order to determine whether the caller can open this key.

The server SHOULD accept an ApiGetRootKey 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.

 HKEY_RPC ApiGetRootKey(
   [in] unsigned long samDesired,
   [out] error_status_t *Status
 );

samDesired: A bitmask that indicates the requested level of access to the root key. 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 root key with the requested access.

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.

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