3.1.4.4 R_WinsDoStaticInit (Opnum 3)

The R_WinsDoStaticInit method performs static initialization of a WINS database by registering the names specified in a data file.

 DWORD R_WinsDoStaticInit(
   [in] handle_t ServerHdl,
   [in, unique, string] LPWSTR pDataFilePath,
   [in] DWORD fDel
 );

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

pDataFilePath: A pointer to a Unicode string containing the path to a text file on the target WINS server. The file SHOULD contain entries that map NetBIOS names to IPv4 addresses in string format using the following syntax:

  
 <IPv4 address 1> <one or more spaces> <NetBIOS name 1>
 <IPv4 address 2> <one or more spaces> <NetBIOS name 2>
 ...
 <IPv4 address N> <one or more spaces> <NetBIOS name N>
  

An example of this syntax can be found in the Windows LMHOSTS file. See [LMHOSTS] for more information.

If this pointer value is NULL, the target WINS server SHOULD use the following default path: "%systemroot%\system32\drivers\etc\lmhosts".

fDel: Value specifying whether or not to delete the file specified by pDataFilePath from the target WINS server. A non-zero value deletes the file from the target WINS server after the database initialization is complete.

Return Values: A 32 bit unsigned integer value that indicates the return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation completed successfully. Any other 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.

0x00000FA2

ERROR_STATIC_INIT_FAILED

An error occurred during static initialization of the database file.

0x00000005

ERROR_ACCESS_DENIED

The caller does not 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 a WINS server that processes a call to R_WinsDoStaticInit:

  • The R_WinsDoStaticInit caller 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 WINS server retrieves the entries from the specified file and registers the retrieved names into the WINS database.

  • After the WINS server finishes the initialization, it removes the file if fDel is set to a nonzero value.

  • The WINS server SHOULD return ERROR_STATIC_INIT_FAILED if any error occurs while the server is reading the file or registering the names in the database.