3.1.4.1 R_WinsRecordAction (Opnum 0)

The R_WinsRecordAction method inserts, modifies, deletes, releases, or queries a name record from the WINS database.

 DWORD R_WinsRecordAction(
   [in] handle_t ServerHdl,
   [in, out, ref] PWINSINTF_RECORD_ACTION_T* ppRecAction
 );

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.<3>

ppRecAction: A pointer to a WINSINTF_RECORD_ACTION_T structure (section 2.2.2.3) that contains the details of the record and the action to be performed on it. The interpretation of the member values in this structure depends on the type of action specified by the WINSINTF_ACT_E enumeration (section 2.2.1.4) value in its Cmd_e member, as follows.

WINSINTF_E_INSERT:

§ Cmd_e is set to WINSINTF_E_INSERT.

§ pName points to a NULL-terminated string that contains the NetBIOS name and optionally the NetBIOS scope name of the record.

§ NameLen contains the length of the string specified by pName.

§ TypOfRec_e is set to a value between 0x00000000 and 0x00000003 based on the record type.

§ NoOfAdds is set to a positive value based on the number of IP address mappings that the record has.

§ pAdd or Add is set with the mapping IP addresses, based on the TypOfRec_e member.

§ VersNo SHOULD be ignored by the server. The inserted record MUST be marked with the current version number that is in use at the WINS server.

§ NodeTyp is set to a value between 0x00 and 0x03 based on the type of the node.

§ OwnerId SHOULD be ignored by the server. The record MUST be inserted into the database with the OwnerId member set to the target WINS server address.

§ State_e SHOULD be ignored by the server. The record MUST be inserted into the database with its state marked as ACTIVE.

§ fStatic is set to 0x00000001 if the record being inserted is a static record; otherwise, it is set to 0x00000000.

§ TimeStamp SHOULD be ignored by the server. The inserted record SHOULD be time-stamped with zero if the fStatic member is set to 0x00000001; otherwise, it SHOULD be time-stamped with the current time on the server plus the refresh interval configured on the server.

WINSINTF_E_DELETE:

§ Cmd_e is set to WINSINTF_E_DELETE.

§ pName points to a NULL-terminated string that contains the NetBIOS name and optionally the NetBIOS scope name of the record to be deleted from the database.

§ NameLen contains the length of the string specified by pName.

§ State_e is set to 0x00000003.

§ All other members SHOULD be ignored by the server.

§ WINSINTF_E_RELEASE:

§ Cmd_e is set to WINSINTF_E_RELEASE.

§ pName points to a NULL-terminated string that contains the NetBIOS name and optionally the NetBIOS scope name of the record.

§ NameLen contains the length of the string specified by pName.

§ TypOfRec_e is set to a value between zero and 0x00000003 based on the record type.

§ NoOfAdds MUST be set to 0x00000001.

§ pAdd or Add is set with the mapping IP address based on the TypOfRec_e member.

§ VersNo, NodeTyp, OwnerId, and fStatic SHOULD be ignored by the server.

§ State_e SHOULD be ignored by the server. The record MUST be inserted with state marked as RELEASED.

§ TimeStamp SHOULD be ignored by the server. The released record SHOULD be time-stamped with 0xFFFFFFFF if the fStatic member is set to 0x00000001; otherwise, it SHOULD be time-stamped with the current time on the server plus the tombstone interval configured on the server.

WINSINTF_E_MODIFY:

§ Cmd_e is set to WINSINTF_E_MODIFY.

§ pName points to a NULL-terminated string that contains the NetBIOS name and optionally the NetBIOS scope name of the record to be modified in the database.

§ NameLen contains the length of the string specified by pName.

§ TypOfRec_e contains the record type to be set for the record matching the pName member in the WINS database.

§ NodeTyp contains the node type to be set for the record matching the pName member in the WINS database.

§ State_e contains the state to be set for the record matching the pName member in the WINS database.

§ fStatic contains the  value to be set for the record matching the pName member in the WINS database.

§ All other members SHOULD be ignored by the server.

WINSINTF_E_QUERY:

§ Cmd_e is set to WINSINTF_E_QUERY.

§ pName points to a NULL-terminated string that contains the NetBIOS name and optionally the NetBIOS scope name of the record to be queried from the database.

§ NameLen contains the length of the string specified by pName.

§ All other members act as output, which are filled by the server if a matching entry is found in the database.

§ TypOfRec_e contains the matching record type.

§ If the TyeOfRec_e member is set to 0x00000000 or 0x00000001, the NoOfAdds member SHOULD contain 0x00000001 or the number of IP addresses that are mapped to the name given in the pName member.

§ If the TypOfRec_e member is set to 0x00000002 or 0x00000003. The RPC method caller SHOULD refer to this member for the set of IP addresses mapped to the name given in the pName member.

§ If the TypOfRec_e member is set to 0x00000000 or 0x00000001. The RPC method caller SHOULD refer to this member for the IP address mapped to the name given in the pName member. If the TypOfRec_e member is set to 0x00000001, the IPAdd member of the Add structure MUST contain 0xFFFFFFFF.

§ VersNo contains the version number of the matching record.

§ NodeTyp contains the node type of the matching record.

§ OwnerId contains the IP address of the owner of the matching record.

§ State_e contains the state of the matching record.

§ fStatic contains the value 0x00000001 if the record is entered into the database by an administrator; otherwise, it contains 0x00000000.

§ TimeStamp contains the time stamp of the record.

Return Values: A 32-bit unsigned integer value that indicates return status. A return value of ERROR_SUCCESS indicates that the operation was completed successfully. Otherwise, the TimeStamp member SHOULD contain one of the following Win32 error codes, as specified in [MS-ERREF]:

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

The name does not exist in the database. This error is returned only if a requested WINSINTF_E_QUERY operation is not successful.

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 Opnum value for this method is 0.

When processing this call, the WINS server MUST do the following:

  • If the action specified is WINSINTF_E_QUERY, the RPC method caller SHOULD have query level access.<4> For all other actions the 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 service on the target WINS server MUST be in the running or paused state for this method to complete successfully. If the service is in initializing or exiting state, ERROR_WINS_INTERNAL status SHOULD be returned.

  • When the RPC method is called with an action set to WINSINTF_E_INSERT, the requested record is inserted into the database. If the record with the same name already exists in the database, name resolution occurs as described in [MS-WINSRA]. The server returns ERROR_WINS_INTERNAL, if any error occurs while performing the resolution or inserting the record.<5>

  • When an RPC method is called with the action set to WINSINTF_E_RELEASE, the state of the matching record is changed to RELEASED in the database. If a matching record is not found, the server returns ERROR_SUCCESS. If any failure occurs during the modification of the record state, ERROR_WINS_INTERNAL is returned.

  • When an RPC method is called with the action set to WINSINTF_E_MODIFY, the database is searched for a matching record. If a match is found, the attributes of the record such as record type, node type, record state, and fstatic are modified according to the requested values. If the matching record's type is either unique or Normal Group and a request comes to modify it to multihomed or Special Group, respectively, an ERROR_WINS_INTERNAL error is returned; otherwise, ERROR_SUCCESS is returned. If the record is not found in the database, the server returns ERROR_SUCCESS.

  • When the RPC method is called with the action set to WINSINTF_E_QUERY, the database is queried for the given name. If a matching record is found, the attributes of the record are returned to the RPC caller. If the record is not found or if any error occurs during attribute retrieval, the server returns an ERROR_REC_NON_EXISTENT error.

  • When the RPC method is called with the action set to WINSINTF_E_DELETE, the matching record is deleted from the database. If a matching record is not found in the database, an ERROR_SUCCESS status code is returned. If any error occurs during the database operations, an ERROR_WINS_INTERNAL is returned. The RPC method caller MUST set state_e to DELETED for this action to succeed.