Share via

3.1.4.2.147 ApiOpenGroupSet (Opnum 164)

  • Article

The ApiOpenGroupSet method<134> instructs the server to open the handle to an existing group set object created by the ApiCreateGroupSet (section 3.1.4.2.146) method. The method establishes context on the server about the interaction of a client with a specified cluster group set by means of the current RPC connection. ApiOpenGroupSet returns a context handle so that the client can refer to the group set in subsequent method calls.

There are several ways by which the client can determine the name of the group set to specify for the lpszGroupSetName parameter. A group set can have a well-known name if the group set was configured as such using implementation-specific methods between servers.

The server SHOULD accept an ApiOpenGroupSet 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.

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

 HGROUPSET_RPC
 ApiOpenGroupSet  (
   [ in, string ] LPCWSTR lpszGroupSetName,
   [ out ] error_status_t *Status,
   [ out ] error_status_t *rpc_status
 );

lpszGroupSetName: A Unicode string that contains the name of the group set.

Status: Indicates the status of this operation. The server MUST set Status to the following error codes for the specified conditions.

Value

Meaning

0x00000000

ERROR_SUCCESS

Success

0x00000046

ERROR_SHARING_PAUSED

The remote server has been paused or is in the process of being started.

0x000013D1

ERROR_CLUSTER_NODE_SHUTTING_DOWN

The cluster node is shutting down.

0x00001768

ERROR_GROUPSET_NOT_FOUND

The cluster group set represented by the lpszGroupSetName parameter is not available for any further requests.

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: This method MUST return a valid HGROUPSET_RPC context handle, as specified in section 2.2.1.11, to indicate success; otherwise, it MUST return NULL.