3.1.4.1.46 ApiGetGroupState (Opnum 45)

  • Article

(Protocol Version 2) 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.1.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 resources are in the state ClusterResourceOnline, the server MUST return the group state ClusterGroupPartialOnline.

  • Otherwise, if all resources are in state ClusterResourceOnline, the server MUST return group state ClusterGroupOnline; if all resources are in state ClusterResourceOffline, the server MUST return 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.

 error_status_t ApiGetGroupState(
   [in] HGROUP_RPC hGroup,
   [out] unsigned long *State,
   [out, string] wchar_t * *NodeName
 );

hGroup: An HGROUP_RPC context handle that was obtained in a previous ApiOpenGroup 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 resources in the group are in the state ClusterResourceOnline.

ClusterGroupOffline

0x00000001

All the resources in the group are in the state ClusterResourceOffline. This is also the state of 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 resource in the group is in state ClusterResourceOnline, but not all resources are in this state. No resources are in the state ClusterResourceOnlinePending, ClusterResourceOfflinePending, or ClusterResourceFailed.

ClusterGroupPending

0x00000004

At least one resource in the group is in 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.

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.