3.1.4.2.30 ApiCreateKey (Opnum 29)

(Protocol Version 3) 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.

The server MUST require that the client have a security access level of "All" (section 3.1.4).

 HKEY_RPC ApiCreateKey(
   [in] HKEY_RPC hKey,
   [in, string] LPCWSTR lpSubKey,
   [in] DWORD dwOptions,
   [in] DWORD samDesired,
   [in, unique] PRPC_SECURITY_ATTRIBUTES lpSecurityAttributes,
   [out] LPDWORD lpdwDisposition,
   [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 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: Ignored by the server.

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 or the client does not have an access level of "All" (section 3.1.4).
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_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.

rpc_status: A 32-bit integer that the RPC runtime MUST write indicating whether or not it succeeded in executing this method on the server. A value of 0x00000000 indicates that the method call was successfully transported to the server, executed with no faults, and returned control to the client without encountering any communication faults. This value is separate from the value returned by the method and does not represent the success of the method. The client MUST treat all nonzero values 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.