18.104.22.168.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 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 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 );
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 top-level resources in the group (resources as specified in section 126.96.36.199.2) are in the state ClusterResourceOnline.
All the resources in the group are in the state ClusterResourceOffline. This is also the state of a 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 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.
At least one resource in the group is in the 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.
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
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 188.8.131.52 as recoverable errors and initiate the reconnect procedure as specified in section 184.108.40.206.