3.1.4.2.43 ApiCreateGroup (Opnum 42)

(Protocol Version 3) The ApiCreateGroup method adds a resource group to the nonvolatile cluster state and establishes context on the server about the interaction of a client with the new group by using the current RPC connection. The method returns a context handle so that the client can refer to the group in subsequent method calls.

The group contains no resources and is hosted on the node to which the current RPC connection was made. The initial persistent state of a group is offline and its preferred hosts list, as described in section 3.1.1.1.4, is initialized as empty.

The group ID MUST be assigned by the cluster at group creation and MUST NOT be changed until the group is deleted.

A group MUST maintain a state sequence number that represents whether a change in the group's state has occurred. This sequence number MUST be initialized to zero when the group is created. The value that the cluster assigns for the group ID is implementation-specific but MUST comply with the requirements specified in section 3.1.1.1.4. The cluster SHOULD assign the group ID with a GUIDString.

The server MUST initialize the group type to 0x0000270F, ClusGroupTypeUnknown.

The server MUST fail the method using ERROR_OBJECT_ALREADY_EXISTS if the group name is same as either the name or the ID of a different group.

The server MUST accept an ApiCreateGroup request for processing only if it is in the read/write state, 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).

Upon success, the server MUST associate a security access level of "All" with the resource context it has established.

 HGROUP_RPC ApiCreateGroup(
   [in, string] LPCWSTR lpszGroupName,
   [out] error_status_t *Status,
   [out] error_status_t *rpc_status
 );

lpszGroupName: A Unicode string that is the name associated with the group.

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_SHARING_PAUSED 0x00000046	The remote server has been paused or is in the process of being started.
ERROR_OBJECT_ALREADY_EXISTS 0x00001392	See the preceding text for when this error can occur.

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.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether the runtime succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for  comm_status and fault_status, as specified in Appendix E of [C706].

Return Values: The method MUST return a valid HGROUP_RPC context handle, as specified in section 2.2.1.3, to indicate success; otherwise, it MUST return NULL.