22.214.171.124 WitnessrRegisterEx (Opnum 4)
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 126.96.36.199, 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:
If set, the client requests notifications only for the registered IP address.
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.
The operation completed successfully.
Access is denied.
Insufficient system resources exist to complete the requested service.
The parameter is incorrect.
The specified resource state is invalid.
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 188.8.131.52. 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 184.108.40.206, 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 220.127.116.11, 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.