3.1.4.2.46 ApiGetGroupState (Opnum 45)

(Protocol Version 3) The ApiGetGroupState method returns the current state of the specified group and the name of the node that owns the group. The group state is determined by the server at the time it is requested; that is, the state of the group is dynamically determined and is based on the configuration and collective set of resource states (section 3.1.4.2.13) that are contained in the group.

The group state is meant to convey an exceptional resource state by using an increasing level of precedence. The group state does not imply the state of all the resources in the group; typically it implies that at least one resource state is exceptional or transitional. Therefore, if the group state is ClusterGroupFailed, it is possible that some resources are in a state other than ClusterResourceFailed. The order of precedence is defined as follows:

• If one or more resources in the group is in the state ClusterResourceFailed, the server MUST return the group state ClusterGroupFailed.

• Otherwise, if one or more resources in the group is in the state ClusterResourceOnlinePending or ClusterResourceOfflinePending, the server MUST return the group state ClusterGroupPending.

• Otherwise, if one or more but not all top-level resources are in the state ClusterResourceOnline, the server MUST return the group state ClusterGroupPartialOnline.

• Otherwise, if all top-level resources are in the state ClusterResourceOnline, the server MUST return the group state ClusterGroupOnline; if all top-level resources are in the state ClusterResourceOffline, the server MUST return the group state ClusterGroupOffline.

The state and ownership of a group SHOULD change according to implementation-specific mechanisms between servers, such as when the cluster detects that a resource that was online has failed.

The group state sequence number MUST be monotonically incremented for any transition between the group states.

The server SHOULD accept an ApiGetGroupState 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 SHOULD accept an ApiGetGroupState request if the access level associated with the hGroup context handle is at least "Read" (section 3.1.4).

 error_status_t ApiGetGroupState(
   [in] HGROUP_RPC hGroup,
   [out] DWORD *State,
   [out, string] LPWSTR *NodeName,
   [out] error_status_t *rpc_status
 );

hGroup: An HGROUP_RPC context handle that was obtained in a previous ApiOpenGroup, ApiOpenGroupEx, or ApiCreateGroup method call.

State: The current state of the group, which is written by the server after successful completion of this method. If the method fails, this parameter MUST be ignored. If the method succeeds, State MUST be set to one of the following values.

Value	Meaning
ClusterGroupOnline 0x00000000	All the top-level resources in the group (resources as specified in section 3.1.1.1.2) are in the state ClusterResourceOnline.
ClusterGroupOffline 0x00000001	All the resources in the group are in the state ClusterResourceOffline. This is also the state of a group that contains no resources.
ClusterGroupFailed 0x00000002	At least one resource in the group has failed; that is, the resources are in the state ClusterResourceFailed.
ClusterGroupPartialOnline 0x00000003	At least one top-level resource in the group is in the state ClusterResourceOnline but not all resources are in this state. No top-level resources are in the state ClusterResourceOnlinePending, ClusterResourceOfflinePending, or ClusterResourceFailed.
ClusterGroupPending 0x00000004	At least one resource in the group is in the state ClusterResourceOnlinePending or ClusterResourceOfflinePending. There are no resources in the state ClusterResourceFailed.
ClusterGroupStateUnknown 0xFFFFFFFF	The operation to retrieve the group state was unsuccessful.

NodeName: The address of a pointer where the server MUST write, upon successful completion of this method, the address of a Unicode string buffer containing the name of the node that currently owns this group. The server MUST allocate as much memory as is required to return the node name. If the method fails, this parameter MUST be ignored.

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 the following error codes for the specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x00000006 ERROR_INVALID_HANDLE	The hGroup parameter does not represent a valid HGROUP_RPC context handle.
0x00001394 ERROR_GROUP_NOT_AVAILABLE	The cluster group is not available for any new requests.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table. However, the client SHOULD treat errors specified in 3.2.4.6 as recoverable errors and initiate the reconnect procedure as specified in section 3.2.4.6.