Export (0) Print
Expand All
Expand Minimize

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] LPCWSTR lpSubKey,
  [in] DWORD dwOptions,
  [in] DWORD samDesired,
  [in, unique] PRPC_SECURITY_ATTRIBUTES lpSecurityAttributes,
  [out] LPDWORD 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.

 
Show:
© 2014 Microsoft