3.1.4.2.137 ApiAddNotifyV2 (Opnum 138)

Article
04/27/2022

(Protocol Version 3) The ApiAddNotifyV2 method SHOULD <123> register for notifications for the object and type specified on an HNOTIFY_RPC context handle previously returned by a call to ApiCreateNotifyV2 (section 3.1.4.2.136). Clients can use this method to register for multiple notifications for a given object in a single call. However, clients MUST call this method for every object for which it needs to receive notifications.

Clients MUST only call this method with an HNOTIFY_RPC handle returned by the ApiCreateNotifyV2 (section 3.1.4.2.136) method. The server MUST use the root key of the cluster registry as the key for which state and configuration changes are monitored if the object type specified in the filter parameter is CLUSTER_OBJECT_TYPE_REGISTRY.

If the filter includes the CLUSTER_CHANGE_REGISTRY_SUBTREE_V2 value, the server MUST extend the scope of monitoring to include 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 ApiAddNotifyV2 request if its protocol server state is read-only and MUST accept the request if its state is read/write, as specified in section 3.1.1.

The server SHOULD accept an ApiAddNotifyV2 request if the client's access level is at least "Read" (section 3.1.4).

 error_status_t ApiAddNotifyV2(
   [in] HNOTIFY_RPC hNotify,
   [in] HGENERIC_RPC hObject,
   [in] NOTIFY_FILTER_AND_TYPE_RPC filter,
   [in] DWORD dwNotifyKey,
   [in] DWORD dwVersion,
   [in] BOOL isTargetedAtObject,
   [out] error_status_t *rpc_status
 );

hNotify: An HNOTIFY_RPC context handle that was obtained in a previous call to ApiCreateNotifyV2 (section 3.1.4.2.136).

hObject: A context handle. The type of handle depends on the value of the filter parameter.

Filter	Context handle
CLUSTER_OBJECT_TYPE_CLUSTER	An HCLUSTER_RPC context handle that was obtained from a call to ApiOpenCluster (section 3.1.4.2.1) or ApiOpenClusterEx (section 3.1.4.2.116).
CLUSTER_OBJECT_TYPE_QUORUM	An HCLUSTER_RPC context handle that was obtained from a call to ApiOpenCluster (section 3.1.4.2.1) or ApiOpenClusterEx (section 3.1.4.2.116).
CLUSTER_OBJECT_TYPE_RESOURCE_TYPE	An HCLUSTER_RPC context handle that was obtained from a call to ApiOpenCluster (section 3.1.4.2.1) or ApiOpenClusterEx (section 3.1.4.2.116).
CLUSTER_OBJECT_TYPE_GROUP	An HGROUP_RPC context handle that was obtained from a call to ApiOpenGroup (section 3.1.4.2.42), ApiOpenGroupEx (section 3.1.4.2.118), or ApiCreateGroup (section 3.1.4.2.43).
CLUSTER_OBJECT_TYPE_RESOURCE	An HRES_RPC context handle that was obtained from a call to ApiOpenResource (section 3.1.4.2.9), ApiOpenResourceEx (section 3.1.4.2.119), or ApiCreateResource (section 3.1.4.2.10).
CLUSTER_OBJECT_TYPE_NETWORK	An HNETWORK_RPC context handle that was obtained from a call to ApiOpenNetwork (section 3.1.4.2.81) or ApiOpenNetworkEx (section 3.1.4.2.120).
CLUSTER_OBJECT_TYPE_NETWORK_INTERFACE	An HNETINTERFACE_RPC context handle that was obtained from a call to ApiOpenNetInterface (section 3.1.4.2.92) or ApiOpenNetInterfaceEx (section 3.1.4.2.121).
CLUSTER_OBJECT_TYPE_NODE	An HNODE_RPC context handle that was obtained from a call to ApiOpenNode (section 3.1.4.2.67) or ApiOpenNodeEx (section 3.1.4.2.117).
CLUSTER_OBJECT_TYPE_REGISTRY	An HKEY_RPC context handle that was obtained from a call to ApiGetRootKey (section 3.1.4.2.29), ApiCreateKey (section 3.1.4.2.30), or ApiOpenKey (section 3.1.4.2.31).
CLUSTER_OBJECT_TYPE_SHARED_VOLUME	An HCLUSTER_RPC context handle that was obtained from a call to ApiOpenCluster (section 3.1.4.2.1) or ApiOpenClusterEx (section 3.1.4.2.116).
CLUSTER_OBJECT_TYPE_SPACEPORT	An HCLUSTER_RPC context handle that was obtained from a call to ApiOpenCluster or ApiOpenClusterEx.
CLUSTER_OBJECT_TYPE_UPGRADE	An HCLUSTER_RPC context handle that was obtained from a call to ApiOpenCluster or ApiOpenClusterEx.
CLUSTER_OBJECT_TYPE_GROUPSET	An HGROUPSET_RPC context handle that was obtained from a call to ApiOpenGroupSet (section 3.1.4.2.147) or ApiCreateGroupSet (section 3.1.4.2.146).

filter: Identifies the notifications for the specified object type that the client is registering for. For details of the NOTIFY_FILTER_AND_TYPE_RPC structure, see section 2.2.3.22. Clients MUST set this structure with the object type, as specified in section 2.2.2.12, and a bitwise-OR of flags from enumerations that correspond to the desired notifications. For some notifications, certain flags are disallowed.

Notification type	Enumeration
CLUSTER_OBJECT_TYPE_CLUSTER	CLUSTER_CHANGE_CLUSTER_V2 (section 2.2.2.12) The client MUST NOT set the following flags: CLUSTER_CHANGE_CLUSTER_RECONNECT_V2, CLUSTER_CHANGE_CLUSTER_HANDLE_CLOSE_V2, CLUSTER_CHANGE_CLUSTER_STATE_V2.
CLUSTER_OBJECT_TYPE_QUORUM	CLUSTER_CHANGE_QUORUM_V2 (section 2.2.2.20)
CLUSTER_OBJECT_TYPE_RESOURCE_TYPE	CLUSTER_CHANGE_RESOURCE_TYPE_V2 (section 2.2.2.15)
CLUSTER_OBJECT_TYPE_GROUP	CLUSTER_CHANGE_GROUP_V2 (section 2.2.2.13) The client MUST NOT set the CLUSTER_CHANGE_GROUP_HANDLE_CLOSE_V2 flag.
CLUSTER_OBJECT_TYPE_RESOURCE	CLUSTER_CHANGE_RESOURCE_V2 (section 2.2.2.14) The client MUST NOT set the CLUSTER_CHANGE_RESOURCE_HANDLE_CLOSE_V2 flag.
CLUSTER_OBJECT_TYPE_NETWORK	CLUSTER_CHANGE_NETWORK_V2 (section 2.2.2.17) The client MUST NOT set the CLUSTER_CHANGE_NETWORK_HANDLE_CLOSE_V2 flag.
CLUSTER_OBJECT_TYPE_NETWORK_INTERFACE	CLUSTER_CHANGE_NETINTERFACE_V2 (section 2.2.2.16) The client MUST NOT set the CLUSTER_CHANGE_NETINTERFACE_HANDLE_CLOSE_V2 flag.
CLUSTER_OBJECT_TYPE_NODE	CLUSTER_CHANGE_NODE_V2 (section 2.2.2.18) The client MUST NOT set the CLUSTER_CHANGE_NODE_HANDLE_CLOSE_V2 flag.
CLUSTER_OBJECT_TYPE_REGISTRY	CLUSTER_CHANGE_REGISTRY_V2 (section 2.2.2.19) The client MUST NOT set the CLUSTER_CHANGE_REGISTRY_HANDLE_CLOSE_V2 flag.
CLUSTER_OBJECT_TYPE_SHARED_VOLUME	CLUSTER_CHANGE_SHARED_VOLUME_V2 (section 2.2.2.21).
CLUSTER_OBJECT_TYPE_SPACEPORT	CLUSTER_CHANGE_SPACEPORT_V2 (section 2.2.2.25).
CLUSTER_OBJECT_TYPE_UPGRADE	CLUSTER_CHANGE_NODE_UPGRADE_PHASE_V2 (section 2.2.2.26).
CLUSTER_OBJECT_TYPE_GROUPSET	CLUSTER_CHANGE_GROUPSET_V2 (section 2.2.2.24). The client MUST NOT set the CLUSTER_CHANGE_GROUPSET_HANDLE_CLOSE_v2 flag.

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 ApiGetNotifyV2 (section 3.1.4.2.138) method, if the name of the object pertaining to the event matches the name of the object indicated by the hObject parameter.

dwVersion: Clients MUST set this value to 2.

isTargetedAtObject: A value of TRUE indicates that the client is registering for notification for a particular object that it MUST specify in the hObject parameter. A value of FALSE indicates that the hObject parameter contains an HCLUSTER_RPC context handle that the client has previously obtained from a call to ApiOpenCluster (section 3.1.4.2.1) or ApiOpenClusterEx (section 3.1.4.2.116).

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: This method MUST return one of the following error codes.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The method completed successfully.
0x00000006 ERROR_INVALID_HANDLE	Either the hNotify parameter does not represent a valid HNOTIFY_RPC context handle, or the hObject parameter does not represent a valid HGENERIC_RPC context handle, or both.
0x00000057 ERROR_INVALID_PARAMETER	Any of the following conditions: The filter parameter contains invalid flags. The filter parameter specifies an invalid object type. The dwVersion parameter contains an invalid value.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The method completed successfully.

0x00000006

ERROR_INVALID_HANDLE

Either the hNotify parameter does not represent a valid HNOTIFY_RPC context handle, or the hObject parameter does not represent a valid HGENERIC_RPC context handle, or both.

0x00000057

ERROR_INVALID_PARAMETER

Any of the following conditions:

The filter parameter contains invalid flags.
The filter parameter specifies an invalid object type.
The dwVersion parameter contains an invalid value.

For any other condition, the server returns a value that is not one of the values listed in the above table. The client MUST treat all values that are not listed in the preceding table identically, except for recoverable errors specified in section 3.2.4.6, for which the client SHOULD initiate the reconnect procedure.

3.1.4.2.137 ApiAddNotifyV2 (Opnum 138)

Additional resources