18.104.22.168.46 ApiGetGroupState (Opnum 45)
(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 22.214.171.124.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 );
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.
All the resources in the group are in the state ClusterResourceOnline.
All the resources in the group are in the state ClusterResourceOffline. This is also the state of group that contains no resources.
At least one resource in the group has failed; that is, the resources are in the state ClusterResourceFailed.
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.
At least one resource in the group is in state ClusterResourceOnlinePending or ClusterResourceOfflinePending. There are no resources in the state ClusterResourceFailed.
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.
The hGroup parameter does not represent a valid HGROUP_RPC context handle.
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 126.96.36.199 as recoverable errors and initiate the reconnect procedure as specified in section 188.8.131.52.