3.1.4.19 R_WinsGetDbRecsByName (Opnum 18)

The R_WinsGetDbRecsByName method retrieves records matching an owner address from a target WINS server database starting at a specified cursor.

 DWORD R_WinsGetDbRecsByName(
   [in] handle_t ServerHdl,
   [in, unique] PWINSINTF_ADD_T pWinsAdd,
   [in] DWORD Location,
   [in, unique, size_is(NameLen + 1)] 
     LPBYTE pName,
   [in] DWORD NameLen,
   [in] DWORD NoOfRecsDesired,
   [in] DWORD fOnlyStatic,
   [out] PWINSINTF_RECS_T pRecs
 );

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: A pointer to the address of the owner WINS server whose records are to be retrieved. If the pointer is NULL, the records for all owners are retrieved.

Location: A value specifying the direction in which the database is searched. If the value is zero, the database is searched forward starting from the beginning. If the value is 1, the database is searched backward starting from the last record of the database.

pName: A pointer to a name that specifies the cursor from which the database retrieval starts.

NameLen: The length of the name that pName points to, including terminating NULL character.

NoOfRecsDesired: The number of records to be retrieved from the database.

fOnlyStatic: Takes a value of 1, 2, or 4 to indicate whether static records, dynamic records, or both are retrieved. A value of 1 retrieves only static records. A value of 2 retrieves only dynamic records. A value of 4 retrieves both static records and dynamic records.

pRecs: A pointer to a structure containing the retrieved records.

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.

0x00000FA5

ERROR_REC_NON_EXISTENT

No records were found matching the given data.

0x00000005

ERROR_ACCESS_DENIED

The caller doesn't 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_WinsGetDbRecsByName:

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

  • This method returns all records whose owner address matches the address specified in pWinsAdd. If pName  points to a valid name, the database search starts from the record after the record whose name matches the valid name. If the name that pName points to does not match the name for any database records, the database search starts from the beginning of the database.

  • A maximum of 5,000 records can be retrieved in a single call.

  • If the owner's address is specified and if the server can't find this address in its owner version map, the server returns error ERROR_WINS_INTERNAL error.

  • If no records match the search criteria, the server returns an ERROR_REC_NON_EXISTENT error. For any other error conditions, the server returns an ERROR_WINS_INTERNAL error.

  • Refer to Retrieving All the Records of a WINS Database (section 4.6) to see how to use R_WinsGetDbRecsByName to retrieve all the records of a database.

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