188.8.131.52.58 ApiAddNotifyCluster (Opnum 57)
(Protocol Version 3) 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 nonvolatile 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 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 184.108.40.206) 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.
The server SHOULD accept an ApiAddNotifyCluster request if the access level associated with the hCluster context handle is at least "Read" (section 3.1.4).
error_status_t ApiAddNotifyCluster( [in] HNOTIFY_RPC hNotify, [in] HCLUSTER_RPC hCluster, [in] DWORD dwFilter, [in] DWORD dwNotifyKey, [out] error_status_t* rpc_status );
dwFilter: A 32-bit integer bitmask containing the bitwise OR operator of one or more values in a CLUSTER_CHANGE (section 220.127.116.11) 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 18.104.22.168.66) method, if the name of the object pertaining to the event matches the name of the object designated by hCluster (the second parameter).
rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether it succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for comm_status and fault_status, as specified in Appendix E of [C706].
Return Values: The method MUST return the following error codes for the specified conditions.
Return value/code Description
The data that is pointed to by the hNotify parameter or the hCluster parameter does not respectively represent a valid HNOTIFY_RPC (section 22.214.171.124) or HCLUSTER_RPC (section 126.96.36.199) 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 188.8.131.52 as recoverable errors and initiate the reconnect procedure as specified in section 184.108.40.206.