3.1.5.4.3 Receiving a Root Referral Response or Link Referral Response

This section describes the processing that occurs when the client gets a referral response after sending a DFS root referral request in step 6 of section 3.1.4.1 or a link referral request in either step 9 of section 3.1.4.1 or in section 3.1.5.1.

If the referral request is successful, but the NumberOfReferrals field in the referral header (as specified in section 2.2.4) is 0, the DFS server could not find suitable targets to return to the client. In this case, the client MUST fail the original I/O operation with STATUS_OBJECT_PATH_NOT_FOUND.

If the referral request returns an NTSTATUS value with the Sev field set to 2 or 3, as specified in [MS-ERREF] section 2.3, process as follows:

• In the case of a referral request sent to a DC (steps 5.4 and 6 of section 3.1.4.1), the client MAY<13> issue a root referral request to the next DC from the DCList of the DomainCache entry, as in step 6 of section 3.1.4.1. If all DCs from the DCList have been tried, the DFS client MUST fail the user/application–initiated I/O operation with STATUS_OBJECT_PATH_NOT_FOUND.

  When the root referral request sent to a DC is successful, the client SHOULD set the DCHint of the DomainCache entry used to that DC. The DCHint serves as a performance optimization for future operations.

• In the case of a link referral request: the client MAY<14> issue a link referral request to the next target from the TargetList of the ReferralCache entry, as in section 3.1.5.2. If all the targets in ReferralCache entry have been tried, the client MUST fail the user/application-initiated I/O operation and return the same NTSTATUS value that was returned to the client.

  When the link referral request sent to a root target is successful, the client SHOULD set the TargetHint of the ReferralCache entry to that root target. The TargetHint serves as a performance optimization for future operations.

• In any other case: the DFS client MUST fail the user/application-initiated I/O operation and return the same NTSTATUS value.

If the client sends a DFS root referral request and receives a referral response with the ServerType field of the referral response entry (as specified in section 2.2.5) set to 0x0000, a link referral response is being returned. <15>

The client can access the null-terminated Unicode DFS target path contained in a referral entry by adding the value in the NetworkAddressOffset field (as specified in section 2.2.4) of the referral entry to the address of the referral entry. The client can access the null-terminated Unicode DFS root or link path that corresponds to the referral response by adding the value in the DFSPathOffset field (as specified in section 2.2.4) of the referral entry to the address of the referral entry.

If this response is due to a referral request that was sent in step 6 of section 3.1.4.1 or section 3.1.5.1 on a ReferralCache miss, the client MUST create a new ReferralCache entry from the referral response and set TargetHint to the first target in TargetList. For a DFS referral version 4 response, the client MUST set TargetSetBoundary of each target in TargetList to the value of the TargetSetBoundary bit of the referral entry (see section 2.2.5.4). The client MUST set the value of RootOrLink in ReferralCache entry based on the ServerType field of the referral entry. The client MUST set the value of the Interlink flag based on the test in section 3.1.5.4.5.

If this response is due to a referral request that was sent in step 2.2 in section 3.1.4.1 to refresh an existing but expired ReferralCache entry, the client MUST perform the following steps:

• Update the TargetList of the ReferralCache entry from the referral response, unless the following condition holds: if the targets contained in the TargetList of the ReferralCache entry and those returned in the referral response are equivalent, the client MUST NOT update the TargetList in the ReferralCache entry. The equivalence check operation is specified as follows:

  • DFS referral version 4 response: The number of target sets is the same, and each target set in the ReferralCache entry and the referral response contain the same targets, independent of their order with the target set.

  • DFS referral version 1, 2, or 3 response: The ReferralCache entry and the referral response contain the same targets, independent of their order.

• Update the TTL and TargetFailback in the ReferralCache entry from the referral response.

• Update the Interlink flag from the referral response, based on the test in section 3.1.5.4.5.

• If the target specified by the TargetHint is not present in the referral response, set the TargetHint to point to the first target of the TargetList in ReferralCache.

• If the TargetFailback is set in the ReferralCache entry, and if the TargetHint is not in the first target set of the TargetList, set the TargetHint to point to the first target in the first target set of the TargetList. This is referred to as a DFS client target failback. Target failback can also be performed at instances other than just at ReferralCache entry refresh time based on an implementation-defined policy.

If an attempt to refresh an existing but expired ReferralCache entry fails, an implementation-defined error behavior MAY be used. For example, the client can initiate ReferralCache entry refresh at the end of a soft time-out period (as specified in section 3.1.1) while permitting the use of the entry and either discard it at the end of a hard time-out period (as specified in section 3.1.1) or fail the I/O operations that use the ReferralCache entry.<16>