Export (0) Print
Expand All
Expand Minimize

3.1.4.2.137 ApiAddNotifyV2 (Opnum 138)

(Protocol Version 3) The ApiAddNotifyV2 method registers 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.

Servers SHOULD<106> support this method.

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).

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

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

hObject: A pointer to a valid context handle. The type of handle depends on the value of the filter parameter.

Filter

Context handle

CLUSTER_OBJECT_TYPE_CLUSTER

A pointer to 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

A pointer to 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

A pointer to 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

A pointer to 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

A pointer to 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

A pointer to 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

A pointer to 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

A pointer to 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

A pointer to 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

A pointer to an HCLUSTER_RPC context handle that was obtained from a call to ApiOpenCluster (section 3.1.4.2.116) or ApiOpenClusterEx (section 3.1.4.2.116).

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 )

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.

isTargetAtObject: 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 a pointer to 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

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 MUST return 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.

 
Show:
© 2015 Microsoft