CreateClusterNotifyPort

The CreateClusterNotifyPort function creates a notification port to handle cluster event notification.

HCHANGE WINAPI CreateClusterNotifyPort(
  HCHANGE hChange,   
  HCLUSTER hCluster, 
  DWORD dwFilter,    
  DWORD dwNotifyKey  
);
 

Parameters

hChange

[in] Handle to a notification port or INVALID_HANDLE_VALUE, indicating that a new handle should be created. If hChange is an existing handle, the events specified in dwFilter are added to the notification port.

hCluster

[in] Handle to the cluster to be associated with the notification port identified by hChange, or INVALID_HANDLE_VALUE, indicating that the notification port should not be associated with a cluster. If hChange is not set to INVALID_HANDLE_VALUE, hCluster cannot be set to INVALID_HANDLE_VALUE.

dwFilter

[in] Bitmask of flags that describes the events to cause notifications to be stored in the queue. One or more of the following flags can be set using the OR operator:

CLUSTER_CHANGE_CLUSTER_PROPERTY

Indicates that a notification should be issued when the prioritized list of internal networks has changed.

CLUSTER_CHANGE_CLUSTER_STATE

This notification is reserved for future use.

CLUSTER_CHANGE_GROUP_ADDED

Indicates that a notification should be issued when a new group is created in the cluster. Groups are created with a call to the CreateClusterGroup function.

CLUSTER_CHANGE_GROUP_DELETED

Indicates that a notification should be issued when an existing group is deleted. Groups are deleted with a call to the DeleteClusterGroup function.

CLUSTER_CHANGE_GROUP_PROPERTY

Indicates that a notification should be issued when the properties of an existing group change. Events that can trigger this notification include calling SetClusterGroupName to change a group's name and adding or removing a resource from a group.

CLUSTER_CHANGE_GROUP_STATE

Indicates that a notification should be issued when a group changes state. For a list of the possible group state values, see GetClusterGroupState.

CLUSTER_CHANGE_HANDLE_CLOSE

Indicates that a notification should be issued when a handle associated with a cluster object has closed.

CLUSTER_CHANGE_NETINTERFACE_ADDED

Indicates that a notification should be issued when a new network interface is added to a cluster node.

CLUSTER_CHANGE_NETINTERFACE_DELETED

Indicates that a notification should be issued when a network interface is permanently removed from a cluster node.

CLUSTER_CHANGE_NETINTERFACE_PROPERTY

Indicates that a notification should be issued when the properties of an existing network interface change.

CLUSTER_CHANGE_NETINTERFACE_STATE

Indicates that a notification should be issued when a network interface changes state. For a list of the possible network interface state values, see GetClusterNetInterfaceState.

CLUSTER_CHANGE_NETWORK_ADDED

Indicates that a notification should be issued when a new network is added to the cluster environment.

CLUSTER_CHANGE_NETWORK_DELETED

Indicates that a notification should be issued when a network is permanently removed from the cluster environment.

CLUSTER_CHANGE_NETWORK_PROPERTY

Indicates that a notification should be issued when the properties of an existing network change.

CLUSTER_CHANGE_NETWORK_STATE

Indicates that a notification should be issued when a network changes state. For a list of the possible network state values, see GetClusterNetworkState.

CLUSTER_CHANGE_NODE_ADDED

Indicates that a notification should be issued when a new node is added to the cluster. A node can only be added when Cluster Server is initially installed on the node.

CLUSTER_CHANGE_NODE_DELETED

Indicates that a notification should be issued 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

This notification is reserved for future use.

CLUSTER_CHANGE_NODE_STATE

Indicates that a notification should be issued when a node changes state. For a list of possible node state values, see GetClusterNodeState.

CLUSTER_CHANGE_QUORUM_STATE

This notification is reserved for future use.

CLUSTER_CHANGE_REGISTRY_ATTRIBUTES

Indicates that a notification should be issued 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

Indicates that a notification should be issued when the name of a cluster database key has changed. Name changes can occur through the ClusterRegCreateKey function which creates a new database key and the ClusterRegDeleteKey function which deletes a key.

CLUSTER_CHANGE_REGISTRY_SUBTREE

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

Indicates that a notification should be issued 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

Indicates that a notification should be issued when a new resource is created in the cluster. Resources can be created with the CreateClusterResource function.

CLUSTER_CHANGE_RESOURCE_DELETED

Indicates that a notification should be issued when a resource is deleted. Resources can be deleted with the DeleteClusterResource function.

CLUSTER_CHANGE_RESOURCE_PROPERTY

Indicates that a notification should be issued when the properties of a resource change. Events that can trigger this notification include changing the name of a resource with SetClusterResourceName, changing a resource's list of possible owner nodes with AddClusterResourceNode and RemoveClusterResourceNode, and changing a resource's dependencies with AddClusterResourceDependency or RemoveClusterResourceDependency.

CLUSTER_CHANGE_RESOURCE_STATE

Indicates that a notification should be issued when a resource changes state. For a list of the possible resource state values, see GetClusterResourceState.

This notification is also issued when a resource is moved from one group to another with ChangeClusterResourceGroup.

CLUSTER_CHANGE_RESOURCE_TYPE_ADDED

Indicates that a notification should be issued when a new resource type is created in the cluster. Resource types can be created with the CreateClusterResourceType function.

CLUSTER_CHANGE_RESOURCE_TYPE_DELETED

Indicates that a notification should be issued when an existing resource type is deleted. Resource types can be deleted with the DeleteClusterResourceType function.

dwNotifyKey

[in] Any value that is to be associated with retrieving notifications from the created notification port. The dwNotifyKey is returned from GetClusterNotify when an event of one of the types specified in dwFilter occurs.

Return Values

NULL

The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, CreateClusterNotifyPort returns a notification port handle.

Remarks

A notification port stores notifications of events occurring within a cluster for applications. Applications register to store events using CreateClusterNotifyPort, setting dwFilter to one or more events of interest and dwNotifyKey to a value that represents the registration. For example, if an application wants to be informed when there is any change to the cluster's resource types, it would set dwFilter to:

CLUSTER_CHANGE_RESOURCE_TYPE_ADDED | CLUSTER_CHANGE_RESOURCE_TYPE_DELETED
 

Once registered, the notification port maintains a queue of notification events. The application must call GetClusterNotify to retrieve the notifications associated with the events and the affected data. An application can have zero or more notification ports.

Applications that want to add other event types after the CreateClusterNotifyPort function has completed can do so by calling RegisterClusterNotify.

To receive notifications of cluster database changes, one or more of the flags applicable to the cluster database must be set in the dwFilter parameter. Applicable flags begin with the prefix CLUSTER_CHANGE_REGISTRY.

By specifying one of the cluster database flags, an application can learn of events that apply to the database root for the cluster specified by the hCluster parameter.

The CLUSTER_CHANGE_HANDLE_CLOSE event is meant to prevent a potential race condition that can occur when one thread trying to close a notification port calls CloseClusterNotifyPort and completes while simultaneously another thread is trying to retrieve an event from this port by calling GetClusterNotify. Prevent this potential problem by having the thread calling GetClusterNotify watch for the CLUSTER_CHANGE_HANDLE_CLOSE notification as follows:

do {
    Status = GetClusterNotify(hChange,...)
    if (Status == ERROR_SUCCESS) {
        if (dwFilter == CLUSTER_CHANGE_HANDLE_CLOSE) {
            //
            // Clean up and terminate
            //
            break;
        }

        // do something
    }
while (Status == ERROR_SUCCESS);
 

For information about the data that is returned to an application when it makes the call to retrieve a notification, see GetClusterNotify.

QuickInfo

  Version: Use Windows NT Server Enterprise Edition 4.0.
  Windows CE: Unsupported.
  Header: Declared in clusapi.h.