RegisterClusterNotify function (clusapi.h)
Adds an event type to the list of events stored for a notification port. The PCLUSAPI_REGISTER_CLUSTER_NOTIFY type defines a pointer to this function.
Syntax
DWORD RegisterClusterNotify(
[in] HCHANGE hChange,
[in] DWORD dwFilterType,
[in] HANDLE hObject,
[in] DWORD_PTR dwNotifyKey
);
Parameters
[in] hChange
Handle to a notification port created with the CreateClusterNotifyPort function.
[in] dwFilterType
Bitmask of flags that describes the event to be added to the set of events currently being monitored by the notification port. For more information about these event types, see CreateClusterNotifyPort. The dwFilterType parameter can be set to one of the following flags.
CLUSTER_CHANGE_CLUSTER_PROPERTY (0x40000000)
The queue receives a notification when the cluster's prioritized list of internal networks changes.
CLUSTER_CHANGE_CLUSTER_RECONNECT
The queue receives a notification when the connection to the cluster identified by hCluster is reestablished after a brief disconnect. Some events generated immediately before or after this event may have been lost. You need 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. This notification is reserved for future use.
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 an existing group change.
CLUSTER_CHANGE_GROUP_STATE (0x00001000)
The queue receives a notification when a group changes state.
CLUSTER_CHANGE_HANDLE_CLOSE (0x80000000)
The queue receives a notification when a handle to 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.
CLUSTER_CHANGE_QUORUM_STATE (0x10000000)
The queue receives a notification when the quorum resource changes state.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES (0x00000020)
The queue receives a notification when a cluster database key's attributes are changed.
CLUSTER_CHANGE_REGISTRY_NAME (0x00000010)
The queue receives a notification when a change to a name is made in the cluster database.
CLUSTER_CHANGE_REGISTRY_SUBTREE (0x00000080)
Indicates that the other CLUSTER_CHANGE_REGISTRY events apply to the root of the cluster database and to all of the subkeys. If CLUSTER_CHANGE_REGISTRY_SUBTREE is not specified, the notifications apply only to the root.
CLUSTER_CHANGE_REGISTRY_VALUE (0x00000040)
The queue receives a notification when a value of the specified cluster database key is changed or deleted.
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)
Indicates that a notification should be issued when the properties of a resource change.
CLUSTER_CHANGE_RESOURCE_STATE (0x00000100)
The queue receives a notification when a resource changes state.
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.
[in] hObject
Handle to the failover cluster object affected by the event specified in the dwFilterType parameter. The type of handle depends on the value of dwFilterType as described in the following list.
CLUSTER_CHANGE_CLUSTER_PROPERTY
HCLUSTER
CLUSTER_CHANGE_CLUSTER_STATE
HCLUSTER
CLUSTER_CHANGE_GROUP_DELETED
HGROUP
CLUSTER_CHANGE_GROUP_PROPERTY
HGROUP
CLUSTER_CHANGE_GROUP_STATE
HGROUP
CLUSTER_CHANGE_HANDLE_CLOSE
HCLUSTER, if the flag is used by itself; otherwise, the handle that is associated with the flag that CLUSTER_CHANGE_HANDLE_CLOSE is combined with becomes the handle type.
For example, if the value of the dwFilterType parameter is CLUSTER_CHANGE_GROUP_PROPERTY | CLUSTER_CHANGE_HANDLE_CLOSE, then the type of handle for the hObject parameter becomes HGROUP, because the CLUSTER_CHANGE_GROUP_PROPERTY flag is associated with the HGROUP handle type.
CLUSTER_CHANGE_NODE_DELETED
HNODE
CLUSTER_CHANGE_NODE_PROPERTY
HNODE
CLUSTER_CHANGE_NODE_STATE
HNODE
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES
HKEY
CLUSTER_CHANGE_REGISTRY_NAME
HKEY
CLUSTER_CHANGE_REGISTRY_SUBTREE
HKEY
CLUSTER_CHANGE_REGISTRY_VALUE
HKEY
CLUSTER_CHANGE_RESOURCE_DELETED
HRESOURCE
CLUSTER_CHANGE_RESOURCE_PROPERTY
HRESOURCE
CLUSTER_CHANGE_RESOURCE_STATE
HRESOURCE
The cluster database functions return a valid cluster database key that can be used to set hObject when dwFilterType is set to an event type affecting the cluster database.
[in] dwNotifyKey
Notification key returned from GetClusterNotify when the requested event occurs.
Return value
If the operation succeeds, the function returns ERROR_SUCCESS.
If the operation fails, the function returns a system error code.
Remarks
The RegisterClusterNotify function enables an application that has already created a notification port with CreateClusterNotifyPort to register for an additional event that affects a node, resource, or group.
To receive notifications of cluster database changes, one or more of the flags applicable to the database must be set in the dwFilterType parameter. Applicable flags start with the prefix CLUSTER_CHANGE_REGISTRY. Making manual changes to the cluster database through the registry editor, RegEdit.exe, does not generate notifications.
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 |