3.1.4.5 WitnessrRegisterEx (Opnum 4)

  • Article

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

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

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.

ShareName:  A pointer to a null-terminated string that specifies the name of the share 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.

Flags:  The type of Witness registration. This field MUST be set to one of the following values:

Value

Meaning

WITNESS_REGISTER_NONE

0x00000000

If set, the client requests notifications only for the registered IP address.

WITNESS_REGISTER_IP_NOTIFICATION

0x00000001

If set, the client requests notifications of any eligible server IP addresses.

KeepAliveTimeout: The maximum number of seconds for any notification response from the server.

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.

This opnum is applicable only to servers that implement Witness protocol version 2.

If the Version field of the request is not 0x00020000, 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.

If ShareName is not NULL, the server MUST enumerate the shares by calling NetrShareEnum as specified in [MS-SRVS] section 3.1.4.8. If the enumeration fails or if no shares are returned, the server MUST return the error code ERROR_INVALID_STATE.

If none of the shares in the list has shi*_type set to STYPE_CLUSTER_SOFS as specified in [MS-SRVS] section 3.1.4.8, the server MUST ignore ShareName.

Otherwise, the server MUST fail the request with the error code ERROR_INVALID_STATE for the following:

  • ShareName does not exist in the enumerated list.

  • 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 and ShareName has shi*_type set to STYPE_CLUSTER_SOFS, as specified in [MS-SRVS] section 2.2.2.4, the server MUST fail the request with ERROR_INVALID_STATE.

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

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

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

  • WitnessRegistration.LastUseTime MUST be set to the current time.

  • WitnessRegistration.KeepAliveTime MUST be set to KeepAliveTimeout.

  • WitnessRegistration.IsAsyncNotifyRegistered MUST be set to FALSE.

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

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

  • If ShareName is not NULL, WitnessRegistration.ShareNameNotificationRequired MUST be set to TRUE; otherwise set to FALSE.

  • If Flags field has WITNESS_REGISTER_IP_NOTIFICATION set, WitnessRegistration.IPNotificationRequired MUST be set to TRUE; otherwise set to FALSE.

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

  • WitnessRegistration.RegistrationKey MUST be set to a newly generated UUID.

  • WitnessRegistration.PendingChangeNotifications, WitnessRegistration.PendingMoveNotification, WitnessRegistration.PendingShareMoveNotification, 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.