3.1.4.1.30 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.

dwOptions:

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.

Value	Meaning
REG_CREATED_NEW_KEY 0x00000001	The key did not exist and was created.
REG_OPENED_EXISTING_KEY 0x00000002	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.

Value	Meaning
ERROR_SUCCESS 0x00000000	Success.
ERROR_ACCESS_DENIED 0x00000005	The client is not permitted to create or open the specified subkey with the wanted access.
ERROR_INVALID_HANDLE 0x00000006	The hKey value does not indicate a valid cluster registry key.
ERROR_SHARING_PAUSED 0x00000046	The remote server has been paused or is in the process of being started.
ERROR_INVALID_PARAMETER 0x00000057	Returned whenever dwOptions is not set to 0x00000000.
ERROR_INVALID_SECURITY_DESCR 0x0000053A	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 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.