3.1.4.18 R_WinsGetBrowserNames (Opnum 17)

  • Article

The R_WinsGetBrowserNames method retrieves browser name records from the target WINS server database. 

 DWORD R_WinsGetBrowserNames(
   [in, ref] WINSIF_HANDLE ServerHdl,
   [out] PWINSINTF_BROWSER_NAMES_T pNames
 );

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. See [MSDN-Handles] for more information.

This value MUST be ignored by the WINS server on receipt.

pNames: A pointer to a structure of type WINSINTF_BROWSER_NAMES_T (section 2.2.2.10), which contains the browser name records retrieved from the target WINS server.

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.

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

Processing and Response Requirements:

Clients with any access level can call this method.

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

  • This method retrieves all browser name records in the target WINS server database.

  • If the Browser name cache abstract data element (section 3.1.1) has been populated, and less than 3 minutes have elapsed since it was last updated, this method SHOULD return the records from the cache by using the pNames parameter.

  • If this method call is being made for the first time, or if 3 minutes or more have elapsed since the Browser name cache was last updated, the cache SHOULD be refreshed by fetching records from the database, and the contents of the cache are returned.

  • If any error occurs while retrieving the records, the service SHOULD return an ERROR_WINS_INTERNAL error code.

The R_WinsGetBrowserNames 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.