Returns information relating to the next notification event stored for a notification port.

Syntax

DWORD WINAPI GetClusterNotify(
  __in      HCHANGE hChange,
  __out     DWORD_PTR *lpdwNotifyKey,
  __out     LPDWORD lpdwFilterType,
  __out     LPWSTR lpszName,
  __inout   LPDWORD lpcchName,
  __in_opt  DWORD dwMilliseconds
);

Parameters

hChange [in]

Handle to a notification port created with the CreateClusterNotifyPort function.

lpdwNotifyKey [out]

Pointer to the notification key for the port identified by hChange.

lpdwFilterType [out]

Pointer to a flag indicating the type of returned event. This flag is one of the following values from the CLUSTER_CHANGE enumeration.

Flag	Meaning
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 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. Windows Server 2003 and Windows 2000:  This value is not supported.
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 a cluster database key's attributes 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.

 

lpszName [out]

Pointer to a null-terminated Unicode string containing the name of the cluster object that triggered the event. The following table 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.

Value of lpdwFilterType	Meaning
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 changed group.
CLUSTER_CHANGE_GROUP_STATE 0x00001000	Name of changed group.
CLUSTER_CHANGE_HANDLE_CLOSE 0x80000000	Name of object being closed.
CLUSTER_CHANGE_NODE_ADDED 0x00000004	Name of new node.
CLUSTER_CHANGE_NODE_DELETED 0x00000002	Name of deleted node.
CLUSTER_CHANGE_NODE_PROPERTY 0x00000008	Name of changed node.
CLUSTER_CHANGE_NODE_STATE 0x00000001	Name of changed node.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES 0x00000020	Relative name of changed cluster database key.
CLUSTER_CHANGE_REGISTRY_NAME 0x00000010	Relative name of changed cluster database key.
CLUSTER_CHANGE_REGISTRY_VALUE 0x00000040	Relative name of 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 changed resource.
CLUSTER_CHANGE_RESOURCE_STATE 0x00000100	Name of changed resource.
CLUSTER_CHANGE_RESOURCE_TYPE_ADDED 0x00020000	Name of new resource type.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED 0x00010000	Name of deleted resource type.

 

lpcchName [in, out]

Pointer to the size of the lpszName buffer as a count of characters. On input, specify 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.

dwMilliseconds [in, optional]

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.

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

See Also

Cluster Management Functions

CreateClusterNotifyPort

CloseClusterNotifyPort

RegisterClusterNotify

CLUSTER_CHANGE

Send comments about this topic to Microsoft

Build date: 11/19/2009