3.1.4.6 R_WinsGetDbRecs (Opnum 5)

  • Article

The R_WinsGetDbRecs method returns the records whose version numbers are within a specified range and that are owned by a specified WINS server.

 DWORD R_WinsGetDbRecs(
   [in] handle_t ServerHdl,
   [in, ref] PWINSINTF_ADD_T pWinsAdd,
   [in] WINSINTF_VERS_NO_T MinVersNo,
   [in] WINSINTF_VERS_NO_T MaxVersNo,
   [out] PWINSINTF_RECS_T pRecs
 );

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

pWinsAdd: Address of an owner WINS server whose records are retrieved from the target WINS server.

MinVersNo: The lower bound on the version range of the records to be retrieved.

MaxVersNo: The upper bound on the version range of the records to be retrieved.

pRecs: Pointer to a structure of type WINSINTF_RECS_T, which contains the records retrieved from the target WINS server.

Return Values: A 32-bit unsigned integer value that indicates the return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation finished successfully. Any nonzero 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 does not have sufficient permissions.

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

Processing and Response Requirements:

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

  • The RPC method caller SHOULD have query-level access.<7> If an RPC client with a lower access level calls R_WinsGetDbRecs, the server SHOULD return ERROR_ACCESS_DENIED.

  • In response to a R_WinsGetDbRecs call, records are retrieved from the target WINS server database if their version numbers fall between MinVersNo and MaxVersNo, and if the records are owned by the owner WINS server whose address is specified by pWinsAdd.

  • If the R_WinsGetDbRecs caller specifies zero for both MinVersNo and MaxVersNo, all records owned by the WINS server specified by pWinsAdd are retrieved from the target WINS server's database.

  • The MinVersNo value MUST be less than or equal to MaxVersNo value for the R_WinsGetDbRecs call to succeed; otherwise, the server SHOULD return ERROR_WINS_INTERNAL.

The R_WinsGetDbRecs caller is responsible for freeing the memory pointed to by pRecs->pRow->pName and pRecs->pRow->pAdd for each record, then using the midl_user_free function (section 3) to free the pRecs->pRow and pRecs pointers themselves.