3.1.4.2 R_WinsStatus (Opnum 1)
The R_WinsStatus method retrieves configuration settings and statistics from a WINS server.
-
DWORD R_WinsStatus( [in] handle_t ServerHdl, [in] WINSINTF_CMD_E Cmd_e, [in, out, ref] PWINSINTF_RESULTS_T pResults );
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.
Cmd_e: The command to be executed on the target WINS server from the WINSINTF_CMD_E enumeration (section 2.2.1.5).
pResults: A pointer to a WINSINTF_RESULTS_T structure (section 2.2.2.7) that contains configuration data and statistics for the target WINS server.
Return Values: A 32-bit unsigned integer value that indicates return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation completed successfully. Otherwise, this 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:
The following requirements and recommendations apply to the WINS server that processes a call to R_WinStatus:
The R_WinStatus caller SHOULD have query level access.<6> If an RPC client with a lower access level calls R_WinStatus, the server SHOULD return ERROR_ACCESS_DENIED.
The WINS service on the target WINS server MUST be in the running or paused state. If the service is in initializing or exiting state, the server SHOULD return ERROR_WINS_INTERNAL.
When R_WinStatus is called with the Cmd_e parameter set to WINSINTF_E_ADDVERSMAP, the first entry of the AddVersMaps array SHOULD contain the address of the WINS server for which the version number is requested. The WINSINTF_E_ADDVERSMAP command retrieves the version number for the specified owner address from the owner version map of the target WINS server. The retrieved version number is stored in the AddVersMaps[0].VersNo parameter. If the address of the owner WINS server is not found in the owner-version map of the target WINS server, an ERROR_WINS_INTERNAL error is returned.
When R_WinStatus is called with the Cmd_e parameter set to WINSINTF_E_CONFIG, the pResults parameter is used only for output. The NoOfOwners and AddVersMaps parameters specify the owner version map table maintained on the target WINS server. If the owner version map table has more than 25 entries, only the first 25 entries are copied to pResults->AddVersMaps. The RefreshInterval, TombstoneInterval, TombstoneTimeout, VerifyInterval, WINSPriorityClass, and NoOfWorkerThds members get values according to the configuration of the target WINS server. The WINSStat parameter is not used for this command. An ERROR_WINS_INTERNAL error is returned if any error occurs during processing of a WINSINTF_E_CONFIG command.
When R_WinStatus is called with the Cmd_e parameter set to WINSINTF_E_CONFIG_ALL_MAPS, the behavior is the same as specified for the WINSINTF_E_CONFIG command except that the owner version map entry is returned even if it is marked as deleted.
When R_WinStatus is called with the Cmd_e parameter set to WINSINTF_E_STAT, the pResults parameter is used only for output. Statistics for the target WINS server are copied to pResults->WINSStat. The pResults->WINSStat.pRplPnrs pointer MUST be NULL for this operation to succeed. The WINSINTF_E_STAT command also retrieves the information retrieved by the WINSINTF_E_CONFIG command. An ERROR_WINS_INTERNAL error is returned if any error occurs during processing of a WINSINTF_E_STAT command.