GetClusterResourceState

The GetClusterResourceState function returns the current state of a resource.

CLUSTER_RESOURCE_STATE WINAPI GetClusterResourceState(
  HRESOURCE hResource,   
  LPWSTR lpszNodeName,   
  LPDWORD lpcchNodeName, 
  LPWSTR lpszGroupName,  
  LPDWORD lpcchGroupName 
);
 

Parameters

hResource

[in] Handle to the resource for which state information should be returned.

lpszNodeName

[out] Pointer to the name of the node in the cluster where the group of the resource identified by hResource is currently online or NULL, if the node name is not required.

lpcchNodeName

[in, out] On input, pointer to a count of characters in the buffer pointed to by lpszNodeName. On output, pointer to a count of characters in the name contained in the buffer pointed to by lpszNodeName, excluding the terminating NULL character.

lpszGroupName

[out] Pointer to the name of the group that has as a member the resource identified by hResource. This parameter can be NULL if the group name is not required.

lpcchGroupName

[in, out] On input, pointer to a count of characters in the buffer pointed to by lpszGroupName, including the terminating NULL character. On output, pointer to a count of characters stored in the buffer pointed to by lpszGroupName, excluding the terminating NULL character. If lpszGroupName is NULL, this parameter is ignored.

Return Values

If the operation was successful, GetClusterResourceState returns the current state of the resource, which can be represented by one of the following values:

If the operation was unsuccessful, this function returns ClusterResourceStateUnknown. ClusterResourceStateUnknown indicates that an error has occurred and the exact state of the resource could not be determined. For more detailed information about the error, call the Win32 function GetLastError.

Remarks

Resource state changes can occur during the failover process or when the administrator manually makes a state transition. When a group is failed over, the states of each resource are altered according to their dependencies on the other resources in the group. The Resource Monitor is responsible for managing these state transitions in response to Cluster Service commands and a resource DLL's response when calls are made to its IsAlive and LooksAlive entry points.

The initial state for any resource is the ClusterResourceOffline state. When a resource is offline, it is unavailable for use by a client or another resource. The Cluster Service may request that the Resource Monitor bring an offline resource online.

To place a resource in the ClusterResourceOffline state, the Resource Monitor calls the resource's Offline entry point function and unloads the resource DLL. The resource is removed from the Resource Monitor's list and any Resource Monitor state related to that resource is discarded.

When a resource is in the ClusterResourceOnline state, it is available for use.

When a resource is in one of the pending states, either ClusterResourceOfflinePending or ClusterResourceOnlinePending, it is in the process of either being brought online or taken offline. The pending states are transitional. If after a predetermined amount of time the resource cannot be brought online or taken offline, the resource is set to the ClusterResourceFailed state.

The pending states are entered whenever the Online or Offline entry points return ERROR_IO_PENDING. The pending states are expected to last less than a few seconds. If the resource DLL does not complete the transition from a pending state to a more stable state within a fixed period of time (typically three minutes), the Cluster Service's Resource Manager terminates the resource by calling its Terminate entry point function and tries again according to the policies defined for the resource.

A resource enters the ClusterResourceFailed state if either its IsAlive or LooksAlive entry point fails. The Cluster Service is subsequently notified by the Resource Monitor which continues to poll the resource to detect transient faults. When the resource recovers, the Resource Monitor brings the resource back online unless the Cluster Service explicitly asks the Resource Monitor to take it offline.

QuickInfo

  Version: Use Windows NT Server Enterprise Edition 4.0.
  Windows CE: Unsupported.
  Header: Declared in clusapi.h.