3.1.4.4 WitnessrAsyncNotify (Opnum 3)

  • Article

The WitnessrAsyncNotify method is used by the client to request notification of registered resource changes from the server.

 DWORD WitnessrAsyncNotify(
         [in] handle_t Handle,
         [in] PCONTEXT_HANDLE_SHARED pContext,
         [out] PRESP_ASYNC_NOTIFY* pResp);
           

Handle:  An RPC binding handle [C706].

pContext: A context handle of type PCONTEXT_HANDLE_SHARED, as specified in section 2.2.1.3, that identifies the client on the server.

pResp:  A pointer to a PRESP_ASYNC_NOTIFY structure, as specified in section 2.2.2.4.

Return Values: Returns 0x00000000 (ERROR_SUCCESS) on success or a nonzero error code, as specified in [MS-ERREF] section 2.2. The most common error codes are listed in the following table.

Return value/code

Description

0x00000000

 ERROR_SUCCESS

The operation completed successfully.

0x00000005

 ERROR_ACCESS_DENIED

Access is denied.

0x000005AA

ERROR_NO_SYSTEM_RESOURCES

Insufficient system resources exist to complete the requested service.

0x00000490

ERROR_NOT_FOUND

The specified resource name is not found.

The server MUST search for the WitnessRegistration in WitnessRegistrationList, where WitnessRegistration.RegistrationKey matches the pContext parameter.

If no matching entry is found, the server MUST fail the request and return the error code ERROR_NOT_FOUND.

If the matching entry is found, and WitnessServiceVersion is 0x00020000, the server MUST update WitnessRegistration.LastUseTime to the current time, and WitnessRegistration.IsAsyncNotifyRegistered to TRUE.

The server MUST wait until either WitnessRegistration.PendingChangeNotifications or WitnessRegistration.PendingMoveNotification are not empty.

If WitnessRegistration.PendingChangeNotifications is not empty, the server MUST construct a RESP_ASYNC_NOTIFY structure as follows:

  • pResp.MessageType: MUST be set to RESOURCE_CHANGE_NOTIFICATION.

  • pResp.MessageBuffer: MUST be set to a RESOURCE_CHANGE structure with the following values:

    • The Length field MUST be set to the size of the RESOURCE_CHANGE structure.

    • If the NewState of the Notification is UNAVAILABLE, the ChangeType field MUST be set to RESOURCE_STATE_UNAVAILABLE, else ChangeType MUST be set to RESOURCE_STATE_AVAILABLE.

    • The ResourceName field MUST be set to the ResourceName of the Notification.

    • If additional entries are present in WitnessRegistration.PendingChangeNotifications, the server MUST continue to add RESOURCE_CHANGE structures to the pResp.MessageBuffer, until no entries remain in the list.

  • pResp.NumberOfMessages: MUST be set to the number of resources changed.

  • pResp.Length: MUST be set to the length of the MessageBuffer field.

If the WitnessRegistration.PendingMoveNotification is not empty, the server MUST construct the structure as follows:

  • pResp.MessageType: MUST be set to CLIENT_MOVE_NOTIFICATION.

  • pResp.MessageBuffer: MUST be set to an IPADDR_INFO_LIST structure with the following values:

    • The Reserved field MUST be set to 0.

    • The IPAddrInstances field MUST be set to the number of available interfaces in InterfaceList for which Interface.InterfaceGroupName matches the Notification.ChangeIndication.

    • For each Interface matched, the server MUST construct an IPADDR_INFO structure as follows: 

      • If Interface.State is AVAILABLE, then the IPADDR_ONLINE flag in the Flags field MUST be set. If Interface.State is UNAVAILABLE, then the IPADDR_OFFLINE flag in the Flags field MUST be set.

      • If Interface.IPv4Address is not empty, the IPV4 field MUST be set to Interface.IPv4Address, and IPADDR_V4 MUST be set in the Flags field.

      • If Interface.IPv6Address is not empty, the IPV6 field MUST be set to Interface.IPv6Address, and IPADDR_V6 MUST be set in the Flags field.

    • The IPADDR_INFO structure MUST be copied into the IPAddrInfo field.

    • The Length field MUST be set to the size of the IPADDR_INFO_LIST structure.

  • pResp.NumberOfMessages: MUST be set to 1.

  • pResp.Length: MUST be set to the length of the MessageBuffer field.

If WitnessServiceVersion is 0x00020000, WitnessRegistration.WitnessClientVersion is 0x00020000, and WitnessRegistration.PendingShareMoveNotification is not empty, the server MUST construct the structure as follows:

  • pResp.MessageType: MUST be set to SHARE_MOVE_NOTIFICATION.

  • pResp.MessageBuffer: MUST be set to an IPADDR_INFO_LIST structure with the following values:

    • The Reserved field MUST be set to 0.

    • The IPAddrInstances field MUST be set to the number of available interfaces in InterfaceList for which Interface.InterfaceGroupName matches the Notification.Destination.

    • For each Interface matched, the server MUST construct an IPADDR_INFO structure as follows: 

      • If Interface.IPv4Address is not empty, the IPV4 field MUST be set to Interface.IPv4Address, and IPADDR_V4 MUST be set in the Flags field.

      • If Interface.IPv6Address is not empty, the IPV6 field MUST be set to Interface.IPv6Address, and IPADDR_V6 MUST be set in the Flags field.

    • The IPADDR_INFO structure MUST be copied into the IPAddrInfo field.

    • The Length field MUST be set to the size of the IPADDR_INFO_LIST structure.

  • pResp.NumberOfMessages: MUST be set to 1.

  • pResp.Length: MUST be set to the length of the MessageBuffer field.

If WitnessServiceVersion is 0x00020000, WitnessRegistration.WitnessClientVersion is 0x00020000, and WitnessRegistration.PendingIPNotification is not empty, the server MUST construct the structure as follows:

  • pResp.MessageType: MUST be set to IP_CHANGE_NOTIFICATION.

  • pResp.MessageBuffer: MUST be set to an IPADDR_INFO_LIST structure with the following values:

    • The Reserved field MUST be set to 0.

    • The IPAddrInstances field MUST be set to the number of available interfaces in InterfaceList for which Interface.InterfaceGroupName matches the Notification.Destination.

    • For each Interface matched, the server MUST construct an IPADDR_INFO structure as follows: 

      • If Interface.IPv4Address is not empty, the IPV4 field MUST be set to Interface.IPv4Address, and IPADDR_V4 MUST be set in the Flags field.

      • If Interface.IPv6Address is not empty, the IPV6 field MUST be set to Interface.IPv6Address, and IPADDR_V6 MUST be set in the Flags field.

    • The IPADDR_INFO structure MUST be copied into the IPAddrInfo field.

    • The Length field MUST be set to the size of the IPADDR_INFO_LIST structure.

  • pResp.NumberOfMessages: MUST be set to 1.

  • pResp.Length: MUST be set to the length of the MessageBuffer field.

The server MUST remove all entries that were processed from WitnessRegistration.PendingChangeNotifications, WitnessRegistration.PendingMoveNotification, WitnessRegistration.PendingShareMoveNotification, and WitnessRegistration.PendingIPNotification.

If WitnessServiceVersion is 0x00020000, the server MUST set WitnessRegistration.LastUseTime to the current time and WitnessRegistration.IsAsyncNotifyRegistered to FALSE.

The server MUST return ERROR_SUCCESS and the pResp parameter to the client.