3.1.4.2.42 ApiOpenGroup (Opnum 41)

(Protocol Version 3) The ApiOpenGroup method establishes context on the server about the interaction of a client with a specified cluster group by means of the current RPC connection. ApiOpenGroup returns a context handle so that the client can refer to the group in subsequent method calls.

There are several ways by which the client can determine the name of the group to specify for the lpszGroupName parameter. A group can have a well-known name if the group was configured as such using implementation-specific methods between servers. Alternatively, a client can use ApiGetResourceState, as specified in 3.1.4.2.13, which returns the name of the group that a resource is contained in.

The server SHOULD accept an ApiOpenGroup request if its protocol server state is read-only and MUST accept the request for processing 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 context it has established.

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

lpszGroupName: A Unicode string that contains the name of the group for which to establish context on the server.

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_GROUP_NOT_FOUND 0x00001395	A group that matches the name lpszGroupName was not found in the cluster configuration.

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 it 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: This 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.