Share via

3.2.4.1 Application Requests Witness Register

  • Article

The caller provides the following:

  • NetName: The name of the application that requests notifications, typically the name to which it has connected.

  • IpAddress: The IP address of the application that requires to receive asynchronous notification.

  • ShareName: A string that contains 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 that implement Witness protocol version 2.

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

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

  • IsIPNotificationRequired: A Boolean when set; indicates that the application requests witness registration to receive notifications based on the IP addresses changes on the server associated with NetName. This parameter is only applicable for clients that implement 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 that runs on the IPAddress, as specified in section 2.1 and use implementation-specific<11> values for authentication level and authentication service. If the connection is not established, the error result MUST be returned to the caller.

The client MUST call the WitnessrGetInterfaceList method, provide 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 that runs on the selected Interface, as specified in section 2.1 and use 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 error result 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, and provide 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 and use 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, provid 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 and use 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.