ApiCreateKey (Opnum 29)

(Protocol Version 2) In response to the ApiCreateKey method, for a successful operation, either the server MUST create the specified key in the cluster registry, or if the key already exists in the cluster registry, the server MUST open the specified key.

If the lpSubKey exists, the server MUST evaluate the security descriptor that is associated with the key against the user authorization context and the wanted access that is expressed in the samDesired parameter in order to determine whether the caller can open this key.

The server MUST accept an ApiCreateKey request only if its protocol server state is read/write, as specified in section 3.1.1.

 HKEY_RPC ApiCreateKey(
   [in] HKEY_RPC hKey,
   [in, string] const wchar_t * lpSubKey,
   [in] unsigned long dwOptions,
   [in] unsigned long samDesired,
   [in, unique] PRPC_SECURITY_ATTRIBUTES lpSecurityAttributes,
   [out] unsigned long * lpdwDisposition,
   [out] error_status_t *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 created or opened. The lpSubKey parameter MUST be either the empty string or a subkey that is a child of the key that is identified by hKey; does not begin with the "\" character; and is not NULL. If lpSubKey is an empty string, the server MUST return an HKEY_RPC context handle that represents the cluster registry key that is represented by hKey.


MUST be set to 0x00000000. Otherwise, the server MUST return ERROR_INVALID_PARAMETER.

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

lpSecurityAttributes: The security attributes data structure that contains the security descriptor for the new key in the lpSecurityDescriptor field. The lpSecurityAttributes parameter MAY be NULL. If lpSecurityAttributes is NULL, the server MUST use a default security descriptor as specified in [MS-DTYP] section 2.4.6 in order to complete the request. If a security descriptor already exists for the key, the specified security descriptor overwrites the existing value of the security descriptor. Handles to cluster registry keys are not inheritable; therefore, the bInheritHandle member of the SECURITY_ATTRIBUTES structure MUST be zero.

lpdwDisposition: If the method succeeds, the server MUST set lpdwDisposition to one of the following values. If the method fails, the client MUST ignore the output value of lpdwDisposition.





The key did not exist and was created.



The key existed and was opened.

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








The client is not permitted to create or open the specified subkey with the wanted access.



The hKey value does not indicate a valid cluster registry key.



The remote server has been paused or is in the process of being started.



Returned whenever dwOptions is not set to 0x00000000.



The security descriptor structure is invalid.

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

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