3.1.4.1.58 ApiAddNotifyCluster (Opnum 57)

(Protocol Version 2) The ApiAddNotifyCluster method instructs the server to begin queuing event indications to the designated version 1 notification port. Event indications correspond to internal cluster volatile and/or non-volatile configuration and/or state changes that map to a value in the designated filter. Indications are queued for all instances of the various cluster objects.

The server MUST queue a separate event indication to the port for every filter that has the CLUSTER_CHANGE (section 2.2.2.7) value set (section 2.2.2.7) that corresponds to the internal event.

The server MUST use the root key of the cluster registry as the key for which state/configuration changes are monitored if any of the following CLUSTER_CHANGE (section 2.2.2.7) values are specified for the filter: CLUSTER_CHANGE_REGISTRY_NAME, CLUSTER_CHANGE_REGISTRY_ATTRIBUTES, CLUSTER_CHANGE_REGISTRY_VALUE, or CLUSTER_CHANGE_REGISTRY_SUBTREE.

If the CLUSTER_CHANGE_REGISTRY_SUBTREE value is included in the filter, the server MUST extend the scope of monitoring to the following: all subkeys, all subkey security descriptors, and all values under the root key. The server MUST also report changes under the specified key and all subkeys.

The server SHOULD accept an ApiAddNotifyCluster request if its protocol server state is read-only and MUST accept the request for processing if it is in the read/write state, as specified in section 3.1.1.

 error_status_t ApiAddNotifyCluster(
   [in] HNOTIFY_RPC hNotify,
   [in] HCLUSTER_RPC hCluster,
   [in] DWORD dwFilter,
   [in] DWORD dwNotifyKey
 );

hNotify: An HNOTIFY_RPC (section 2.2.1.6) context handle that was obtained in a previous ApiCreateNotify (section 3.1.4.1.56) method call.

hCluster: An HCLUSTER_RPC (section 2.2.1.1) context handle that was obtained in a previous ApiOpenCluster (section 3.1.4.1.1) method call.

dwFilter: A 32-bit integer bitmask containing the bitwise OR operator of one or more values in a CLUSTER_CHANGE (section 2.2.2.7) enumeration. This parameter MUST NOT have any of the following values set: CLUSTER_CHANGE_CLUSTER_STATE, CLUSTER_CHANGE_CLUSTER_RECONNECT, or CLUSTER_CHANGE_HANDLE_CLOSE.

dwNotifyKey: A 32-bit integer context value chosen by the client. This value MUST be returned to the client via a subsequent completion of the ApiGetNotify (section 3.1.4.1.66) method, if the name of the object pertaining to the event matches the name of the object designated by hCluster (the second parameter).

Return Values: The method MUST return the following error codes for the specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x00000006 ERROR_INVALID_HANDLE	The data that is pointed to by the hNotify parameter or the hCluster parameter does not respectively represent a valid HNOTIFY_RPC (section 2.2.1.6) or HCLUSTER_RPC (section 2.2.1.1) context handle.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table. The client SHOULD treat errors specified in section 3.2.4.6 as recoverable errors and initiate the reconnect procedure as specified in section 3.2.4.6.