GetClusterNodeId function (clusapi.h)

Article
02/22/2024

Returns the unique identifier of a cluster node. The PCLUSAPI_GET_CLUSTER_NODE_ID type defines a pointer to this function.

Syntax

DWORD GetClusterNodeId(
  [in, optional] HNODE   hNode,
  [out]          LPWSTR  lpszNodeId,
  [in, out]      LPDWORD lpcchName
);

Parameters

[in, optional] hNode

Handle to the node with the identifier to be returned or NULL. If hNode is set to NULL, the node identifier for the node on which the application is running is returned in the content of lpszNodeId.

[out] lpszNodeId

This parameter points to a buffer that receives the unique ID of hNode, including the terminating NULL character.

[in, out] lpcchName

On input, pointer to the count of characters in the buffer pointed to by the lpszNodeId parameter, including the NULL terminator. On output, pointer to the count of characters stored in the buffer excluding the NULL terminator.

Return value

This function returns a system error code. The following are the possible values:

Return code/value	Description
ERROR_SUCCESS 0	The operation completed successfully.
ERROR_MORE_DATA 234 (0xEA)	More data is available. This value is returned if the buffer pointed to by lpszNodeId is not long enough to hold the required number of characters. GetClusterNodeId sets the content of lpcchName to the required length.

Remarks

The PCLUSAPI_GET_CLUSTER_NODE_ID type defines a pointer to this function.

If hNode is set to NULL and the caller is running on an active cluster node, the GetClusterNodeId function returns the identifier of the node on which the application is running. Setting hNode to NULL is a convenient way for resource DLLs to determine the node identifier of the node they are running on. The GetCurrentClusterNodeId macro can be used instead of passing NULL for the hNode parameter.

A cluster node identifier is a unique identifier that does not change even if the node's name is changed.

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.

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