GetClusterGroupState function (clusapi.h)

Article
10/13/2021

Returns the current state of a group. The PCLUSAPI_GET_CLUSTER_GROUP_STATE type defines a pointer to this function.

Syntax

CLUSTER_GROUP_STATE GetClusterGroupState(
  [in]                HGROUP  hGroup,
  [out, optional]     LPWSTR  lpszNodeName,
  [in, out, optional] LPDWORD lpcchNodeName
);

Parameters

[in] hGroup

Handle to the group for which state information should be returned.

[out, optional] lpszNodeName

Pointer to a null-terminated Unicode string containing the name of the node that currently owns the group.

[in, out, optional] lpcchNodeName

Pointer to the size of the lpszNodeName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return value

GetClusterGroupState returns the current state of the group, which is represented by one of the following values.

Return code/value	Description
ClusterGroupStateUnknown -1	The operation was not successful. For more information about the error, call the function GetLastError.
ClusterGroupOnline 0	All of the resources in the group are online.
ClusterGroupOffline 1	All of the resources in the group are offline or there are no resources in the group.
ClusterGroupFailed 2	At least one resource in the group has failed (set a state of ClusterResourceFailed from the CLUSTER_RESOURCE_STATE enumeration).
ClusterGroupPartialOnline 3	At least one resource in the group is online. No resources are pending or failed.
ClusterGroupPending 4	At least one resource in the group is in a pending state. There are no failed resources.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Do not call GetClusterGroupState from any resource DLL entry point function. GetClusterGroupState can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2008 Enterprise, Windows Server 2008 Datacenter
Target Platform	Windows
Header	clusapi.h
Library	ClusAPI.lib
DLL	ClusAPI.dll