GetClusterNotify function (clusapi.h)
Returns information relating to the next notification event that is stored for a notification port. The PCLUSAPI_GET_CLUSTER_NOTIFY type defines a pointer to this function.
Syntax
DWORD GetClusterNotify(
[in] HCHANGE hChange,
[out] DWORD_PTR *lpdwNotifyKey,
[out] LPDWORD lpdwFilterType,
[out] LPWSTR lpszName,
[in, out] LPDWORD lpcchName,
[in, optional] DWORD dwMilliseconds
);
Parameters
[in] hChange
The handle to a notification port that is created with the CreateClusterNotifyPort function.
[out] lpdwNotifyKey
A pointer to the notification key for the port that is identified by the hChange parameter.
[out] lpdwFilterType
A pointer to a flag that indicates the type of returned event. This flag is one of the following values from the CLUSTER_CHANGE enumeration.
CLUSTER_CHANGE_CLUSTER_PROPERTY (0x40000000)
The queue receives a notification when the cluster's prioritized list of internal networks changes.
CLUSTER_CHANGE_CLUSTER_RECONNECT (0x00080000)
The queue receives a notification when the connection to the cluster identified by the
hCluster parameter is reestablished after a brief disconnect. Some events generated
immediately before or after this event might have been lost. You have to close all open connections and
reconnect to receive accurate state information.
CLUSTER_CHANGE_CLUSTER_STATE (0x20000000)
The queue receives a notification when the cluster becomes unavailable, meaning that all attempts to communicate with the cluster fail.
CLUSTER_CHANGE_GROUP_ADDED (0x00004000)
The queue receives a notification when a new group is created in the cluster.
CLUSTER_CHANGE_GROUP_DELETED (0x00002000)
The queue receives a notification when an existing group is deleted.
CLUSTER_CHANGE_GROUP_PROPERTY (0x00008000)
The queue receives a notification when the properties of a group change or when a resource is added or removed from a group.
CLUSTER_CHANGE_GROUP_STATE (0x00001000)
The queue receives a notification when a group changes state. For a list of the possible group state values, see GetClusterGroupState.
CLUSTER_CHANGE_HANDLE_CLOSE (0x80000000)
The queue receives a notification when a handle associated with a cluster object is closed.
CLUSTER_CHANGE_NETINTERFACE_ADDED (0x04000000)
The queue receives a notification when a new network interface is added to a cluster node.
CLUSTER_CHANGE_NETINTERFACE_DELETED (0x02000000)
The queue receives a notification when a network interface is permanently removed from a cluster node.
CLUSTER_CHANGE_NETINTERFACE_PROPERTY (0x08000000)
The queue receives a notification when the properties of an existing network interface change.
CLUSTER_CHANGE_NETINTERFACE_STATE (0x01000000)
The queue receives a notification when a network interface changes state. For a list of the possible network interface state values, see GetClusterNetInterfaceState.
CLUSTER_CHANGE_NETWORK_ADDED (0x00400000)
The queue receives a notification when a new network is added to the cluster environment.
CLUSTER_CHANGE_NETWORK_DELETED (0x00200000)
The queue receives a notification when a network is permanently removed from the cluster environment.
CLUSTER_CHANGE_NETWORK_PROPERTY (0x00800000)
The queue receives a notification when the properties of an existing network change.
CLUSTER_CHANGE_NETWORK_STATE (0x00100000)
The queue receives a notification when a network changes state. For a list of the possible network state values, see GetClusterNetworkState.
CLUSTER_CHANGE_NODE_ADDED (0x00000004)
The queue receives a notification when a new node is added to the cluster. A node can be added only when the Cluster service is initially installed on the node.
CLUSTER_CHANGE_NODE_DELETED (0x00000002)
The queue receives a notification when a node is permanently removed from a cluster. A node can be permanently deleted from an existing cluster with a call to the EvictClusterNode function.
CLUSTER_CHANGE_NODE_PROPERTY (0x00000008)
This notification is reserved for future use.
CLUSTER_CHANGE_NODE_STATE (0x00000001)
The queue receives a notification when a node changes state. For a list of possible node state values, see GetClusterNodeState.
CLUSTER_CHANGE_QUORUM_STATE (0x10000000)
This notification is reserved for future use.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES (0x00000020)
The queue receives a notification when the attributes of a cluster database key are changed. The only currently defined cluster database key attribute is its security descriptor, which can be changed with ClusterRegSetKeySecurity.
CLUSTER_CHANGE_REGISTRY_NAME (0x00000010)
The queue receives a notification when the name of a cluster database key has changed.
CLUSTER_CHANGE_REGISTRY_SUBTREE (0x00000080)
Indicates that the other CLUSTER_CHANGE_REGISTRY events apply to the entire cluster database. If this flag is not included, the events apply only to the specified key.
CLUSTER_CHANGE_REGISTRY_VALUE (0x00000040)
The queue receives a notification when a value of the specified cluster database key is changed or deleted. Cluster database values can be changed with the ClusterRegSetValue function and deleted with the ClusterRegDeleteValue function.
CLUSTER_CHANGE_RESOURCE_ADDED (0x00000400)
The queue receives a notification when a new resource is created in the cluster.
CLUSTER_CHANGE_RESOURCE_DELETED (0x00000200)
The queue receives a notification when a resource is deleted.
CLUSTER_CHANGE_RESOURCE_PROPERTY (0x00000800)
The queue receives a notification when the properties, dependencies, or possible owner nodes of a resource change.
CLUSTER_CHANGE_RESOURCE_STATE (0x00000100)
The queue receives a notification when a resource changes state. For a list of the possible resource state values, see GetClusterResourceState.
CLUSTER_CHANGE_RESOURCE_TYPE_ADDED (0x00020000)
The queue receives a notification when a new resource type is created in the cluster.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED (0x00010000)
The queue receives a notification when an existing resource type is deleted.
CLUSTER_CHANGE_RESOURCE_TYPE_PROPERTY (0x00040000)
The queue receives a notification when the properties of a resource type change.
[out] lpszName
A pointer to a null-terminated Unicode string containing the name of the cluster object that triggered the event. The following list describes the content of lpszName by event type. Note that CLUSTER_CHANGE_REGISTRY_SUBTREE is not included in the table; this event type is never handled by GetClusterNotify.
CLUSTER_CHANGE_CLUSTER_PROPERTY (0x40000000)
Name of the changed cluster.
CLUSTER_CHANGE_CLUSTER_RECONNECT (0x00080000)
Name of the disconnected cluster.
CLUSTER_CHANGE_CLUSTER_STATE (0x20000000)
Name of the changed cluster.
CLUSTER_CHANGE_GROUP_ADDED (0x00004000)
New group name.
CLUSTER_CHANGE_GROUP_DELETED (0x00002000)
Deleted group name.
CLUSTER_CHANGE_GROUP_PROPERTY (0x00008000)
Name of the changed group.
CLUSTER_CHANGE_GROUP_STATE (0x00001000)
Name of the changed group.
CLUSTER_CHANGE_HANDLE_CLOSE (0x80000000)
Name of the object that is being closed.
CLUSTER_CHANGE_NODE_ADDED (0x00000004)
Name of new node.
CLUSTER_CHANGE_NODE_DELETED (0x00000002)
Name of the deleted node.
CLUSTER_CHANGE_NODE_PROPERTY (0x00000008)
Name of the changed node.
CLUSTER_CHANGE_NODE_STATE (0x00000001)
Name of the changed node.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES (0x00000020)
Relative name of the changed cluster database key.
CLUSTER_CHANGE_REGISTRY_NAME (0x00000010)
Relative name of the changed cluster database key.
CLUSTER_CHANGE_REGISTRY_VALUE (0x00000040)
Relative name of the changed cluster database key.
CLUSTER_CHANGE_RESOURCE_ADDED (0x00000400)
New resource name.
CLUSTER_CHANGE_RESOURCE_DELETED (0x00000200)
Deleted resource name.
CLUSTER_CHANGE_RESOURCE_PROPERTY (0x00000800)
Name of the changed resource.
CLUSTER_CHANGE_RESOURCE_STATE (0x00000100)
Name of the changed resource.
CLUSTER_CHANGE_RESOURCE_TYPE_ADDED (0x00020000)
Name of new resource type.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED (0x00010000)
Name of the deleted resource type.
[in, out] lpcchName
A pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters that the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
[in, optional] dwMilliseconds
Optional time-out value that specifies how long the caller is willing to wait for the notification.
Return value
If the operation succeeds, the function returns ERROR_SUCCESS.
If the operation fails, the function returns a system error code. The following are possible values.
| Return code/value | Description |
|---|---|
|
The handle that is represented in the hChange parameter is invalid or has been closed by another thread. |
|
The call timed out before the notification could be successfully returned. |
|
The buffer pointed to by the lpszName parameter is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL. |
Remarks
Note that the lpcchName parameter 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.
The notifications are asynchronous, and the state of the cluster at the time that the application processes the notification can be different than the state of the cluster at the time the notification was generated.
Examples
See the Notification Port 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 |