OpenClusterEx function (clusapi.h)

Opens a connection to a cluster and returns a handle to it.

Syntax

HCLUSTER OpenClusterEx(
  [in, optional]  LPCWSTR lpszClusterName,
  [in]            DWORD   DesiredAccess,
  [out, optional] DWORD   *GrantedAccess
);

Parameters

[in, optional] lpszClusterName

Specifies one of the following values:

• Pointer to a null-terminated Unicode string containing the name of the cluster or one of the cluster nodes expressed as a NetBIOS name, a fully qualified DNS name, or an IP address. This produces an RPC cluster handle.
• NULL, which produces an LPC handle to the cluster to which the local computer belongs.

[in] DesiredAccess

The requested access privileges. This may be any combination of GENERIC_READ (0x80000000), GENERIC_ALL (0x10000000), or MAXIMUM_ALLOWED (0x02000000). If this value is zero (0) and undefined error may be returned. Using GENERIC_ALL is the same as calling OpenCluster.

[out, optional] GrantedAccess

Optional parameter that contains the address of a DWORD that will receive the access rights granted. If the DesiredAccess parameter is MAXIMUM_ALLOWED (0x02000000) then the DWORD pointed to by this parameter will contain the maximum privileges granted to this user.

Return value

If the operation was successful, OpenClusterEx returns a cluster handle.

Remarks

A cluster handle is a pointer to an internally defined structure which stores information about the RPC or LPC connection to the cluster. Any object handles obtained from the cluster handle will be associated with the RPC or LPC session data stored in the cluster structure. Combining RPC and LPC handles or using handles obtained from different contexts can cause exceptions or other unpredictable results. For more information, see LPC and RPC Handles.

When finished with a cluster handle, it is important to call CloseCluster to ensure that all memory is freed and the connection is shut down cleanly.

Requirements