3.1.4.10 R_WinsPullRange (Opnum 9)

The R_WinsPullRange method pulls a range of records owned by a WINS server from another WINS server, and replicates them within the target WINS server database.<8>

 DWORD R_WinsPullRange(
   [in] handle_t ServerHdl,
   [in, ref] PWINSINTF_ADD_T pWinsAdd,
   [in, ref] PWINSINTF_ADD_T pOwnerAdd,
   [in] WINSINTF_VERS_NO_T MinVersNo,
   [in] WINSINTF_VERS_NO_T MaxVersNo
 );

ServerHdl: An RPC binding over IP address/HostName to the WINS server. RPC uses this binding internally to determine which WINS server the call is directed to.

pWinsAdd: The address of the WINS server from which the entries are pulled.

pOwnerAdd: The address of the owner WINS server whose entries are pulled.

MinVersNo: The lower bound on the range of version numbers for the records to be pulled.

MaxVersNo: The upper bound on the range of version numbers for the records to be pulled.

Return Values: A 32 bit unsigned integer that indicates the return status. A return value of ERROR_SUCCESS (0x00000000) indicates that operation completed successfully. A nonzero return value is a Win32 error code, as specified in [MS-ERREF]. The following Win32 error codes can be returned:

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x00000FA0

ERROR_WINS_INTERNAL

An error occurred while processing the RPC call.

0x00000005

ERROR_ACCESS_DENIED

The caller doesn't have sufficient permissions.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

Processing and Response Requirements:

When R_WinsPullRange is called, the server returns immediately without waiting for the actual pull. It just queues a request for the pull operation, and the actual pull starts at a time determined by the current state and configuration of the target WINS server. Hence, R_WinsPullRange callers SHOULD NOT treat an ERROR_SUCCESS return value as indicating a successful pull operation. Instead, callers SHOULD rely on WINS event logs to determine whether or not the pull operation succeeded. The following table lists the events that indicate the status of a pull operation.

Event ID

Event Name

Event Description

Informational events

4104

WINS_EVT_NO_PULL_RECS

There are no pull records.

4124

WINS_EVT_UPD_NTF_NOT_ACCEPTED

The WINS server received an update notification from the nonconfigured WINS server at the address, %1. The WINS server rejected it. This means the remote WINS server is not in the list of Push partners (WINS servers under the Pull key) and the administrator has prohibited (by using the registry) replication with nonconfigured WINS servers. To have this WINS server accept update notifications from nonconfigured WINS servers, set the Wins\Parameters\RplOnlyWCnfPnrs value in the registry to zero.

4126

WINS_EVT_ADD_VERS_MAP_REQ_NOT_ACCEPTED

The WINS server received a pull request from the nonconfigured WINS server with the address, %1. The WINS server rejected it since the remote WINS server is not in the list of Pull partners (WINS servers under the Pull key) and the administrator has prohibited (using the registry) replication with nonconfigured partners. If you want this WINS server to accept update notifications from WINS servers not in the pull partner list, set the "replication only with configured partners" value in the registry to zero.

4141

WINS_EVT_REC_PULLED

WINS pulled records from a WINS while doing %1. The partner's address and the owner's address whose records were pulled are in the data section (second and third DWORD respectively). The number of records pulled is the fourth DWORD.

4142

WINS_EVT_CC_NO_RECS

WINS performed a consistency check on the records. The number of records pulled, the address of the WINS whose records were pulled, and the address of the WINS from which these records were pulled are given in the second, third, and fourth DWORDs in the data section.

4231

WINS_EVT_CANT_QUERY_PULL_KEY

WINS could not get information about the Pull key. Check whether the permissions on the key are set properly, system resources are low, or the registry is having a problem.

4235

WINS_EVT_CANT_OPEN_PULL_SUBKEY

WINS could not open a Pull subkey. Check whether the permissions on the key are set properly, system resources are low, or the registry is having a problem.

4237

WINS_EVT_CANT_GET_PULL_TIMEINT

WINS could not get the time interval from a Pull record.

4243

WINS_EVT_RPLPULL_PUSH_NTF_EXC

WINS Pull thread encountered an error during the process of sending a push notification to another WINS. The error code is in the data section.

4255

WINS_EVT_PUSH_PNR_INVALID_ADD

WINS has been asked to pull its entries. Check all the Pull subkeys of this WINS.

4273

WINS_EVT_PULL_RANGE_EXC

An error was encountered while trying to service a pull range request from a remote WINS. The exception code is the second DWORD of the data section.

4284

WINS_EVT_EXC_PULL_TRIG_PROC

WINS encountered an exception while processing a pull trigger.

Warning events

4161

WINS_EVT_PARTIAL_RPL_TYPE

A nonzero replication type applies for this partner. This means only a subset of records will be replicated between the local WINS and this partner. To get records that did not replicate, either pull them by using the winscl.exe in the Windows 2000 Resource Kit (as described in [MSFT-ResourceKits]), or delete all owners acquired only through this partner and then initiate replication to reacquire all their records. The partner's address is given in the second DWORD of the data section.

Error events

4178

WINS_EVT_CANT_OPEN_PULL_KEY

The WINS Pull configuration key could not be created or opened. Check to see if the permissions on the key are set properly, system resources are low, or the registry is having a problem.

4194

WINS_EVT_CANT_CREATE_NTF_SOCK

WINS could not create the User Datagram Protocol (UDP) socket to listen for Connection notification messages sent by another Pull thread in the local WINS.

The following requirements and recommendations apply to a WINS server that processes a call to R_WinsPullRange:

  • R_WinsPullRange callers SHOULD have control level access. If an RPC client with a lower access level calls this method, the server SHOULD return ERROR_ACCESS_DENIED.

  • The value of MinVersNo MUST be less than or equal to the value of MaxVersNo. Otherwise, the server SHOULD return ERROR_WINS_INTERNAL.

  • If the target WINS server is configured to pull records only from configured partners, the WINS server address given in pWinsAdd MUST have been configured as a pull partner for the target WINS server. Otherwise, the server SHOULD return ERROR_WINS_INTERNAL.

  • When the client queues a request to pull the records owned by the server whose address is given in pOwnerAdd from the WINS server whose address is given in pWinsAdd, the RPC call SHOULD return immediately without waiting for the replication operation to complete.