3.1.4.2.144 ApiAddNotifyResourceTypeV2 (Opnum 155)

  • Article

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

Clients MUST call this method only with an HNOTIFY_RPC handle returned by the ApiCreateNotifyV2 (section 3.1.4.2.136) method.

The server SHOULD accept an ApiAddNotifyResourceV2 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 ApiAddNotifyResourceV2 request if the client's access level is at least "Read" (section 3.1.4).

 error_status_t ApiAddNotifyResourceTypeV2(
     [ in ] HNOTIFY_RPC hNotify,
     [ in ] LONGLONG filter,
     [ in ] DWORD dwNotifyKey,
     [ in ] LPCWSTR resTypeName,
     [ in ] DWORD dwVersion,
     [ 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).

filter: Identifies the notifications for the specified object type for which the client is registering. Clients MUST set this field with a bitwise-OR of flags from enumerations that correspond to the desired notifications. For some notifications, certain flags are disallowed. See CLUSTER_CHANGE_RESOURCE_TYPE_V2 (section 2.2.2.15) for more details.

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.

resTypeName: A Unicode string that is the name of the type of resource that will execute this operation.

dwVersion: Clients MUST set this value to 2.

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