GetClusterResourceState function (clusapi.h)

Article
10/13/2021

Returns the current state of a resource. The PCLUSAPI_GET_CLUSTER_RESOURCE_STATE type defines a pointer to this function.

Syntax

CLUSTER_RESOURCE_STATE GetClusterResourceState(
  [in]                HRESOURCE hResource,
  [out, optional]     LPWSTR    lpszNodeName,
  [in, out, optional] LPDWORD   lpcchNodeName,
  [out, optional]     LPWSTR    lpszGroupName,
  [in, out, optional] LPDWORD   lpcchGroupName
);

Parameters

[in] hResource

Handle specifying the resource for which state information should be returned.

[out, optional] lpszNodeName

Pointer to a buffer that receives the name of the specified resource's current owner node as a NULL-terminated Unicode string. Pass NULL if the node name is not required.

[in, out, optional] lpcchNodeName

Pointer to the size of the lpszNodeName buffer as a count of characters. This pointer cannot be NULL unless lpszNodeName is also NULL. On input, specifies 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.

[out, optional] lpszGroupName

Pointer to a buffer that receives the name of the group that contains the specified resource. The name is returned as a NULL-terminated Unicode string. Pass NULL if the group name is not required.

[in, out, optional] lpcchGroupName

Pointer to the size of the lpszGroupName buffer as a count of characters. This pointer cannot be NULL unless lpszNodeName is also NULL. On input, specifies 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

GetClusterResourceState returns the current state of the resource enumerated from the CLUSTER_RESOURCE_STATE enumeration, which can be represented by one of the following values.

Return code/value	Description
ClusterResourceInitializing 1	The resource is performing initialization.
ClusterResourceOnline 2	The resource is operational and functioning normally.
ClusterResourceOffline 3	The resource is not operational. This value will be returned if the resource reported a state of ClusterResourceOffline (3) or ClusterResourceCannotComeOnlineOnThisNode (127).
ClusterResourceFailed 4	The resource has failed. This value will be returned if the resource reported a state of ClusterResourceFailed (4) or ClusterResourceCannotComeOnlineOnAnyNode (126).
ClusterResourcePending 128	The resource is in the process of coming online or going offline.
ClusterResourceOnlinePending 129	The resource is in the process of coming online.
ClusterResourceOfflinePending 130	The resource is in the process of going offline.
ClusterResourceStateUnknown -1	The operation was not successful. For more information about the error, call the function GetLastError.

Remarks

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

Examples

See Getting Object States for an example.

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

Share via