3.2.4.1 Application Requests Witness Register

  • Article

The caller provides the following:

  • NetName: The name that the application is requesting for notifications, typically the name to which it has connected.

  • IpAddress: The IP address for which the application requires receiving asynchronous notification.

  • ShareName: A string containing the share name on which the application had requested for notifications, typically the share name to which it has connected. This parameter is only applicable for clients implementing Witness protocol version 2.

  • IsNetNameNotificationRequired: A Boolean when set; indicates that the application is requesting witness registration for receiving notifications based on the NetName. This parameter is only applicable for clients implementing Witness protocol version 2.

  • IsShareNameNotificationRequired: A Boolean when set; indicates that the application is requesting witness registration for receiving notifications based on the ShareName. This parameter is only applicable for clients implementing Witness protocol version 2.

  • IsIPNotificationRequired: A Boolean when set; indicates that the application is requesting witness registration for receiving notifications based on the IP addresses changes on the server associated with NetName. This parameter is only applicable for clients implementing Witness protocol version 2.

If the NetName parameter is an IPv4 address as dotted-decimal with four parts or an IPv6 address as 8 hexadecimal numbers separated by colons, the client MUST return an implementation-specific error to the calling application.

The client MUST establish an RPC connection to the Witness Service running on the IPAddress, as specified in section 2.1 using implementation-specific<11> values for authentication level and authentication service. If the connection is not established, the resulting error MUST be returned to the caller.

The client MUST call the WitnessrGetInterfaceList method, by providing the RPC handle returned from the previous step as the Handle input parameter, and subsequently close the RPC handle. If the server returns an error, the client MUST return the same error code to the caller.

If the server returns STATUS_SUCCESS, the client MUST select an Interface returned in the WITNESS_INTERFACE_LIST where the INTERFACE_WITNESS flag is set in the Flags field and State is AVAILABLE.

If WitnessClientVersion is 0x00020000, the client MUST create a new WitnessRegistration entry in WitnessRegistrationList and set WitnessRegistration.WitnessServerVersion to the Version value returned in the WitnessrGetInterfaceList response and set WitnessRegistration.IpAddress to the IpAddress.

The client MUST establish an RPC Connection to the Witness Service running on the selected Interface, as specified in section 2.1 using implementation-specific<12> values for authentication level and authentication service. If the IPv4 flag is set, the address in Interface.IPv4 SHOULD be used for the connection. If the IPv6 flag is set, the address in Interface.IPv6 SHOULD be used for the connection. If the connection is not established, the resulting error MUST be returned to the caller.

If WitnessClientVersion is 0x00020000, and if IsShareNameNotificationRequired or IsIPNotificationRequired provided by the application is TRUE, the client MUST call the RPC WitnessrRegisterEx method on the resulting RPC handle, providing the following values:

  • WitnessClientVersion for the Version parameter

  • NetName for the NetName parameter

  • ShareName for the ShareName parameter

  • IpAddress for the IpAddress parameter

  • A name to be used to identify the client<13> for ClientComputerName

  • If IsIPNotificationRequired is TRUE, 0x00000001 for Flags; otherwise 0x00000000 for Flags.

  • An implementation-specific time out value for the KeepAliveTimeout parameter.<14>

If the server returns an error, the client MUST retry the registration using other entries returned by the server for the WitnessrGetInterfaceList response. If all the entries are exhausted, the client MUST again call the WitnessrGetInterfaceList method as specified earlier. The client SHOULD<15> retry this registration sequence until it gets STATUS_SUCCESS from the server. If the server returns STATUS_SUCCESS, the client MUST update WitnessRegistration entry with the following values:

  • WitnessServerName: This value MUST be set to the NetName parameter.

  • ShareName: This value MUST be set to ShareName parameter.

  • RegistrationKey: This value MUST be set to the value in the ppContext parameter.

  • RPCHandle: This value MUST be set to the RPC handle used in the previous step.

  • WitnessNotifyRequest: This value MUST be set to FALSE.

  • NetNameNotificationRequired: This value MUST be set to TRUE.

  • ShareNameNotificationRequired: This value MUST be set to TRUE if IsShareNameNotificationRequired is TRUE; otherwise set to FALSE.

  • IPNotificationRequired: This value MUST be set to TRUE if IsIPNotificationRequired is TRUE; otherwise set to FALSE.

Otherwise, the client MUST call the RPC WitnessrRegister method on the resulting RPC handle, providing 0x00010001 for Version, NetName, IpAddress, and a name to be used to identify the client<16>, as input parameters. If the server returns an error, the client MUST retry the registration using other entries returned by the server for the WitnessrGetInterfaceList response. If all the entries are exhausted, the client MUST again call the WitnessrGetInterfaceList method as specified earlier. The client SHOULD<17> retry this registration sequence until it gets STATUS_SUCCESS from the server. If the server returns STATUS_SUCCESS, the client MUST create a new WitnessRegistration entry with the following values, insert the entry in WitnessRegistrationList, and return success to the caller:

  • WitnessServerName: This value MUST be set to the NetName parameter.

  • IPAddress: This value MUST be set to the IpAddress parameter.

  • RegistrationKey: This value MUST be set to the value in the ppContext parameter.

  • WitnessNotifyRequest: This value MUST be set to FALSE.

  • RPCHandle: This value MUST be set to the RPC handle used in the previous step.

  • If WitnessClientVersion is 0x00020000, ShareName MUST be set to NULL, NetNameNotificationRequired MUST be set to TRUE, ShareNameNotificationRequired MUST be set to FALSE, and IPNotificationRequiredRequired MUST be set to FALSE.

The client MUST return success to the caller.