3.1.4.2 WitnessrRegister (Opnum 1)

  • Article

The WitnessrRegister method allows the witness client to register for resource state change notifications of a NetName and IPAddress. The client can subsequently call the WitnessrAsyncNotify method to receive notifications when there is a state change on any of these resources.

 DWORD WitnessrRegister(
         [in] handle_t Handle,
         [out] PPCONTEXT_HANDLE ppContext,
         [in] ULONG Version,
         [in] [string] [unique] LPWSTR NetName,
         [in] [string] [unique] LPWSTR IpAddress,
         [in] [string] [unique] LPWSTR ClientComputerName);
           

Handle: An RPC binding handle [C706].

ppContext: A context handle of type PPCONTEXT_HANDLE, as specified in section 2.2.1.2, that identifies the client on the server.

Version:  The version of the Witness protocol currently in use by the client.

NetName:  A pointer to a null-terminated string that specifies the name of the resource for which the client requires notifications.

IpAddress:  A pointer to a null-terminated string that specifies the IP address to which the client application connection is established.

ClientComputerName:  A pointer to a null-terminated string that is used to identify the Witness client.

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.

0x00000057

ERROR_INVALID_PARAMETER

The parameter is incorrect.

0x0000139F

ERROR_INVALID_STATE

The specified resource state is invalid.

0x0000051A

ERROR_REVISION_MISMATCH

The client request contains an invalid Witness protocol version.

If the Version field of the request is not 0x00010001, the server MUST stop processing the request and return the error code ERROR_REVISION_MISMATCH.

If NetName, IpAddress or ClientComputerName is NULL, the server MUST fail the request and return the error code ERROR_INVALID_PARAMETER.

If the NetName parameter is not equal to ServerGlobalName, the server MUST fail the request and return the error code ERROR_INVALID_PARAMETER.

The server MUST enumerate the shares by calling NetrShareEnum as specified in [MS-SRVS] section 3.1.4.8. In the enumerated list, if any of the shares has shi*_type set to STYPE_CLUSTER_SOFS, as specified in [MS-SRVS] section 2.2.2.4, the server MUST search for an Interface in InterfaceList, where Interface.IPv4Address or Interface.IPv6Address matches the IpAddress parameter based on its format. If no matching entry is found, the server MUST fail the request and return the error code ERROR_INVALID_STATE.

The server MUST create a WitnessRegistration entry as follows and insert it into the WitnessRegistrationList.

  • WitnessRegistration.WitnessClientName MUST be set to the ClientComputerName parameter.

  • WitnessRegistration.NetworkName MUST be set to the NetName parameter.

  • WitnessRegistration.IPAddress MUST be set to the IPAddress parameter.

  • WitnessRegistration.RegistrationKey MUST be set to a UUID generated by the server.

  • WitnessRegistration.PendingChangeNotifications and WitnessRegistration.PendingMoveNotification MUST be set to empty.

If WitnessServiceVersion is 0x00020000, the server MUST set the following values in WitnessRegistration entry:

  • WitnessRegistration.WitnessClientVersion MUST be set to the value of the Version parameter value in the request.

  • WitnessRegistration.ShareName MUST be set to empty.

  • WitnessRegistration.ShareNameNotificationRequired MUST be set to FALSE.

  • WitnessRegistration.IPNotificationRequired MUST be set to FALSE.

  • WitnessRegistration.PendingShareMoveNotification MUST be set to empty

  • WitnessRegistration.PendingIPNotification MUST be set to empty.

The server MUST copy the WitnessRegistration.RegistrationKey into the ppContext parameter.

The server MUST return ERROR_SUCCESS and the ppContext parameter to the caller.