3.1.4.2.138 ApiGetNotifyV2 (Opnum 139)

Article
04/27/2022

(Protocol Version 3) The ApiGetNotifyV2 method is an asynchronous RPC method that SHOULD <124> instruct the server to return a set of queued events from a designated version 2 notification port corresponding to a particular context handle. The server MUST NOT complete this method until an indication has been queued to the port or the port has been closed through a separate call to the ApiUnblockGetNotifyCall (section 3.1.4.2.107) or ApiCloseNotify (section 3.1.4.2.57) method.

The server MUST return the notification enumeration values registered by the client as specified in ApiAddNotifyV2 (section 3.1.4.2.137).

The server MUST NOT return these notification filter flags:

CLUSTER_CHANGE_CLUSTER_RECONNECT_V2
CLUSTER_CHANGE_CLUSTER_STATE_V2
CLUSTER_CHANGE_CLUSTER_HANDLE_CLOSE_V2
CLUSTER_CHANGE_CLUSTER_GROUP_HANDLE_CLOSE_V2
CLUSTER_CHANGE_CLUSTER_RESOURCE_HANDLE_CLOSE_V2
CLUSTER_CHANGE_CLUSTER_NETWORK_HANDLE_CLOSE_V2
CLUSTER_CHANGE_CLUSTER_NETINTERFACE_HANDLE_CLOSE_V2
CLUSTER_CHANGE_CLUSTER_NODE_HANDLE_CLOSE_V2
CLUSTER_CHANGE_CLUSTER_REGISTRY_HANDLE_CLOSE_V2
CLUSTER_CHANGE_CLUSTER_REGISTRY_SUBTREE_V2

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

The server MUST require that the access level associated with the hResource parameter is "Read" (section 3.1.4).

 error_status_t ApiGetNotifyV2(
   [in] HNOTIFY_RPC hNotify,
   [out, size_is (,*dwNumNotifications)] 
     PNOTIFICATION_RPC* Notifications,
   [out] DWORD *dwNumNotifications
 );

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

Notifications: A pointer to an array of one or more NOTIFICATION_RPC (section 2.2.3.24) structures corresponding to notification events that have been generated on the designated notification port since the previous call to ApiGetNotifyV2 or since the client registered for events with ApiAddNotifyV2. For each NOTIFICATION_RPC element in the array, the dwNotifyKey member is set to the value provided by the client in the previous ApiAddNotifyV2 call corresponding to the event indication contained in the NOTIFICATION_RPC structure. Each NOTIFICATION_RPC structure contains a NOTIFICATION_DATA_RPC (section 2.2.3.23) structure, which is populated according to the particular notification event.

For event indications pertaining to a cluster object, as specified for CLUSTER_OBJECT_TYPE_CLUSTER (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_CLUSTER (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_CLUSTER_V2 (section 2.2.2.12) enumeration, indicating the event that occurred.
ObjectId: an empty Unicode string.
Type: an empty Unicode string.
dwBufferSize: the number of bytes in the buffer field.

The remaining fields are set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer	ObjectId	ParentId	Name
CLUSTER_CHANGE_CLUSTER_GROUP _ADDED_V2	A DWORD containing the type of the group.	The ID of the group.	The ID of the node where the group is hosted.	The name of the group
CLUSTER_CHANGE_CLUSTER_NETWORK _ADDED_V2	Empty.	The ID of the cluster network.	An empty Unicode string.	The name of the cluster network.
CLUSTER_CHANGE_CLUSTER_NODE _ADDED_V2	A DWORD containing the state of the node, as specified in 3.1.4.2.69	The ID of the cluster node.	An empty Unicode string.	The name of the cluster node.
CLUSTER_CHANGE_CLUSTER_RESOURCE _TYPE_ADDED_V2	Empty.	An empty Unicode string.	An empty Unicode string.	The name of the new resource type.
CLUSTER_CHANGE_CLUSTER_COMMON _PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.	An empty Unicode string.	An empty Unicode string.	An empty Unicode string.
CLUSTER_CHANGE_CLUSTER_PRIVATE _PROPERTY	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.	An empty Unicode string.	An empty Unicode string.	An empty Unicode string.
CLUSTER_CHANGE_CLUSTER_LOST _NOTIFICATIONS_V2	Empty.	An empty Unicode string.	An empty Unicode string.	An empty Unicode string.
CLUSTER_CHANGE_CLUSTER _RENAME_V2	Empty.	An empty Unicode string.	An empty Unicode string.	The new name of the cluster.
CLUSTER_CHANGE_CLUSTER _MEMBERSHIP_V2	A CLUSTER_MEMBERSHIP_INFO (section 2.2.3.42) containing new information about the cluster membership.	An empty Unicode string.	An empty Unicode string.	An empty Unicode string.
CLUSTER_CHANGE_CLUSTER _UPGRADED_V2	A DWORD containing the cluster operating version.	An empty Unicode string.	An empty Unicode string.	An empty Unicode string.

For event indications pertaining to a group object as specified for CLUSTER_OBJECT_TYPE_GROUP (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_GROUP (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_GROUP_V2 (section 2.2.2.13) enumeration, indicating the event that occurred.
ParentId: ID of the node on which the group is hosted.
Type: an empty Unicode string.
dwBufferSize: the number of bytes in the buffer field.

The remaining fields are set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer	ObjectId	Name
CLUSTER_CHANGE_GROUP_DELETED_V2	Empty.	The ID of the group.	The name of the group.
CLUSTER_CHANGE_GROUP_COMMON_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.	The ID of the group.	The name of the group.
CLUSTER_CHANGE_GROUP_PRIVATE_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.	The ID of the group.	The name of the group.
CLUSTER_CHANGE_GROUP_STATE_V2	A DWORD containing the new group state (see section 3.1.4.2.46).	The ID of the group.	The name of the group.
CLUSTER_CHANGE_GROUP_OWNER_NODE_V2	The ID of the new owner node.	The ID of the group.	The name of the group.
CLUSTER_CHANGE_GROUP_PREFERRED_OWNER_V2	A MULTI_SZ list of string IDs of the preferred owners, as would be set for a multiSzNodeList in a call to ApiSetGroupNodeList (section 3.1.4.2.55).	The ID of the group.	The name of the group.
CLUSTER_CHANGE_GROUP_RESOURCE_ADDED_V2	The ID of the group.	The ID of the resource created in the cluster and contained in this group (see ApiCreateResource (section 3.1.4.2.10)).	The name of the resource created in the cluster and contained in this group (see ApiCreateResource (section 3.1.4.2.10)).
CLUSTER_CHANGE_GROUP_RESOURCE_GAINED_V2	The ID of the resource added to this group, either by ApiCreateResource (section 3.1.4.2.10) or ApiChangeResourceGroup (section 3.1.4.2.26) or ApiChangeResourceGroupEx (section 3.1.4.2.166).	The ID of the group.	The name of the group.
CLUSTER_CHANGE_GROUP_RESOURCE_LOST_V2	The ID of the resource removed from this group, either by ApiDeleteResource (section 3.1.4.2.11) or ApiChangeResourceGroup (section 3.1.4.2.26) or ApiChangeResourceGroupEx (section 3.1.4.2.166).	The ID of the group.	The name of the group.

For event indications pertaining to a resource object as specified for CLUSTER_OBJECT_TYPE_RESOURCE (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_RESOURCE (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_RESOURCE_V2 (section 2.2.2.14) enumeration, indicating the event that occurred.
ObjectId: ID of the resource.
ParentId: ID of the group that contains the resource.
Name: the name of the resource.
Type: the name of the resource type.
dwBufferSize: the number of bytes in the buffer field.

The remaining fields are set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer
CLUSTER_CHANGE_RESOURCE_COMMON_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.
CLUSTER_CHANGE_RESOURCE_PRIVATE_PROPERTY_V2	Empty.
CLUSTER_CHANGE_RESOURCE_STATE_V2	A DWORD containing the resource state (see 3.1.4.2.13).
CLUSTER_CHANGE_RESOURCE_OWNER_GROUP_V2	The ID of the group that now contains the resource.
CLUSTER_CHANGE_RESOURCE_DEPENDENCIES_V2	A new dependency expression, as would be returned by a call to ApiGetResourceDependencyExpression (section 3.1.4.2.110).
CLUSTER_CHANGE_RESOURCE_DEPENDENTS_V2	A MULTI_SZ list of resource ID strings that now list this resource as a provider.
CLUSTER_CHANGE_RESOURCE_POSSIBLE_OWNERS_V2	A MULTI_SZ list of node IDs that can host the resource.
CLUSTER_CHANGE_RESOURCE_DELETED_V2	The ID of the group that contained the resource before it was deleted.
CLUSTER_CHANGE_RESOURCE_DLL_UPGRADED_V2	The ID of the node that issued CLUSCTL_RESOURCE_UPGRADED_DLL (section 3.1.4.3.1.27).

For event indications pertaining to a resource type object as specified for CLUSTER_OBJECT_TYPE_RESOURCE_TYPE (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_RESOURCE_TYPE (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_RESOURCE_TYPE_V2 (section 2.2.2.15) enumeration, indicating the event that occurred.
ObjectId: An empty Unicode string.
ParentId: An empty Unicode string.
Name: the name of the resource type.
Type: An empty Unicode string.
dwBufferSize: the number of bytes in the buffer field.

The buffer field is set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED_V2	Empty.
CLUSTER_CHANGE_RESOURCE_TYPE_COMMON_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.
CLUSTER_CHANGE_RESOURCE_TYPE_PRIVATE_PROPERTY_V2	Empty.
CLUSTER_CHANGE_RESOURCE_TYPE_POSSIBLE_OWNERS_V2	A MULTI_SZ list of cluster node IDs that can host this resource type.
CLUSTER_CHANGE_RESOURCE_TYPE_DLL_UPGRADED_V2	The ID of the node that issued CLUSCTL_RESOURCE_UPGRADED_DLL (section 3.1.4.3.1.27).
CLUSTER_RESOURCE_TYPE_SPECIFIC_V2	The same buffer field that a resource DLL used when it raised the notification.

For event indications pertaining to a cluster network interface as specified for CLUSTER_OBJECT_TYPE_NETWORK_INTERFACE (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_NETWORK_INTERFACE (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_NETINTERFACE_V2 (section 2.2.2.16) enumeration, indicating the event that occurred.
ObjectId: ID of the cluster network interface.
ParentId: ID of the node associated with the cluster network interface.
Name: the name of the cluster network interface.
Type: An empty Unicode string.
dwBufferSize: the number of bytes in the buffer field.

The buffer field is set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer
CLUSTER_CHANGE_NETINTERFACE_DELETED_V2	Empty.
CLUSTER_CHANGE_NETINTERFACE_COMMON_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.
CLUSTER_CHANGE_NETINTERFACE_PRIVATE_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.
CLUSTER_CHANGE_NETINTERFACE_STATE_V2	A DWORD containing the cluster network interface state as would be returned from a call to ApiGetNetInterfaceState (section 3.1.4.2.94).

For event indications pertaining to a cluster network object as specified for CLUSTER_OBJECT_TYPE_NETWORK (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_NETWORK (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_NETWORK_V2 (section 2.2.2.17) enumeration, indicating the event that occurred.
ObjectId: ID of the cluster network.
ParentId: An empty Unicode string.
Name: the name of the cluster network.
Type: An empty Unicode string.
dwBufferSize: the number of bytes in the buffer field.

The buffer field is set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	Buffer
CLUSTER_CHANGE_NETWORK_DELETED_V2	Empty.
CLUSTER_CHANGE_NETWORK_COMMON_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.
CLUSTER_CHANGE_NETWORK_PRIVATE_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.
CLUSTER_CHANGE_NETWORK_STATE_V2	A DWORD containing the cluster network state, as would be returned by a call to ApiGetNetworkState (section 3.1.4.2.83).

For event indications pertaining to a cluster node object as specified for CLUSTER_OBJECT_TYPE_NODE (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_NODE (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_NODE_V2 (section 2.2.2.18) enumeration, indicating the event that occurred.
ParentId: An empty Unicode string.
Type: An empty Unicode string.
dwBufferSize: the number of bytes in the buffer field.

The remaining fields are set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer	ObjectId	Name
CLUSTER_CHANGE_NODE_NETINTERFACE_ADDED_V2	The ID of the cluster node.	The ID of the cluster network interface.	The name of the cluster network interface.
CLUSTER_CHANGE_NODE_DELETED_V2	A DWORD containing the state of the cluster node as would be returned from a call to ApiGetNodeState (section 3.1.4.2.69).	The ID of the cluster node.	The name of the cluster node.
CLUSTER_CHANGE_NODE_COMMON_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.	The ID of the cluster node.	The name of the cluster node.
CLUSTER_CHANGE_NODE_PRIVATE_PROPERTY_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) with updated values.	The ID of the cluster node.	The name of the cluster node.
CLUSTER_CHANGE_NODE_STATE_V2	A DWORD containing the state of the cluster node as would be returned from a call to ApiGetNodeState (section 3.1.4.2.69).	The ID of the cluster node.	The name of the cluster node.
CLUSTER_CHANGE_NODE_GROUP_GAINED_V2	The ID of the group that has moved to this node.	The ID of the cluster node.	The name of the cluster node.
CLUSTER_CHANGE_NODE_GROUP_LOST_V2	The ID of the group that has moved away from this node.	The ID of the cluster node.	The name of the cluster node.

For event indications pertaining to a cluster registry key object as specified for CLUSTER_OBJECT_TYPE_REGISTRY (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_REGISTRY (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_REGISTRY_V2 (section 2.2.2.19) enumeration, indicating the event that occurred.
ParentId: An empty Unicode string.
Type: An empty Unicode string.
buffer: An empty buffer.
dwBufferSize: 0x00000000.

The remaining fields are set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	ObjectId	Name
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES_V2	An empty Unicode string.	Relative name of the cluster database key whose attributes changed.
CLUSTER_CHANGE_REGISTRY_NAME_V2	The name of the changed value.	Relative name of the renamed cluster database key.
CLUSTER_CHANGE_REGISTRY_SUBTREE_V2	An empty Unicode string.	An empty Unicode string.
CLUSTER_CHANGE_REGISTRY_VALUE_V2	The name of the changed value.	Relative name of the changed cluster database key.

For event indications pertaining to a cluster quorum as specified for CLUSTER_OBJECT_TYPE_QUORUM (section 2.2.2.11), the server MUST set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_QUORUM (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_QUORUM_V2 (section 2.2.2.19) enumeration, indicating the event that occurred.
ParentId: NULL.
Type: NULL.
dwBufferSize: the number of bytes in the buffer field.

The remaining fields are set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer	ObjectId	Name
CLUSTER_CHANGE_QUORUM_STATE_V2	A DWORD describing the new state of the resource, as would be returned from a call to ApiGetResourceState (section 3.1.4.2.13).	The ID of the resource.	The name of the resource.

Note For the CLUSTER_CHANGE_QUORUM_STATE_V2 value, if and only if a quorum disk resource is included, a payload will also be provided and the target will be the resource.

For event indications pertaining to a shared volume as specified for CLUSTER_OBJECT_TYPE_SHARED_VOLUME (section 2.2.2.11), the server SHOULD <125> set the NOTIFICATION_DATA_RPC structure as follows:

FilterAndType.dwObjectType: CLUSTER_OBJECT_TYPE_SHARED_VOLUME (section 2.2.2.11).
FilterAndType.FilterFlags: one flag from the CLUSTER_CHANGE_SHARED_VOLUME_V2 (section 2.2.2.21) enumeration, indicating the event that occurred.
ParentId: NULL.
Type: NULL.
dwBufferSize: the number of bytes in the buffer field.

The remaining fields are set depending on the event that occurred, identified by the FilterAndType.FilterFlags field, as specified in the following table.

FilterAndType.FilterFlags	buffer	ObjectId	Name
CLUSTER_CHANGE_SHARED_VOLUME_STATE_V2	A Property List (section 2.2.3.10) containing one or more Property Values (section 2.2.3.10.1) of type binary value, with each binary data value representing a CLUSTER_SHARED_VOLUME_STATE_INFO_EX (section 2.2.3.32) structure.	The ID of the cluster shared volume resource.	The name of the cluster shared volume resource.

dwNumNotifications: A pointer to a DWORD that contains the count of NOTIFICATION_RPC structures.

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 the following error codes for the following conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The method completed successfully.
0x00000006 ERROR_INVALID_HANDLE	The data that is pointed to by the hNotify parameter does not represent a valid HNOTIFY_RPC context handle.
0x00000103 ERROR_NO_MORE_ITEMS	The notification port represented by the hNotify parameter has been closed.
0x00000001 ERROR_INVALID_FUNCTION	Either the ApiUnblockGetNotifyCall (section 3.1.4.2.107) method or the ApiCloseNotify (section 3.1.4.2.57) method has been called in another thread. The client SHOULD terminate the notification thread.

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

3.1.4.2.138 ApiGetNotifyV2 (Opnum 139)

Additional resources