3.1.4.1 User/Application Initiated I/O Operation on a UNC Path

  • Article

The calling application provides:

  • Implementation-specific information on the I/O operation to be performed.

  • Path indicating the UNC path on which the I/O operation is to be performed.

  • UserCredentials to be used for performing I/O operation on the UNC path.

  • MaxOutputSize indicating the maximum output buffer size, in bytes.

When the DFS client receives an I/O operation with a UNC path, it MUST normalize the UNC path to the protocol format with one leading backslash (as specified in section 2.2.1) and perform a name resolution. See the following flowcharts for an illustration of the process. In some cases, individual steps have a description of the condition at entry of the step inside square brackets [like this].

The following flowcharts show the steps taken by a DFS client to resolve a DFS path.

DFS path resolution – initial steps

Figure 1: DFS path resolution – initial steps

DFS path resolution – connection 2

Figure 2: DFS path resolution – connection 2

DFS path resolution - connection 3

Figure 3: DFS path resolution - connection 3

DFS path resolution - connection 4

Figure 4: DFS path resolution - connection 4

DFS path resolution - connection 5

Figure 5: DFS path resolution - connection 5

DFS path resolution - connection 6

Figure 6: DFS path resolution - connection 6

DFS path resolution - connection 7

Figure 7: DFS path resolution - connection 7

DFS path resolution - connection 8

Figure 8: DFS path resolution - connection 8

DFS path resolution - connection 9

Figure 9: DFS path resolution - connection 9

DFS path resolution - connection 10

Figure 10: DFS path resolution - connection 10

DFS path resolution - connection 11

Figure 11: DFS path resolution - connection 11

DFS path resolution - connection 12

Figure 12: DFS path resolution - connection 12

DFS path resolution - connection 13

Figure 13: DFS path resolution - connection 13

DFS path resolution - connection 14

Figure 14: DFS path resolution - connection 14

 The following procedure specifies a possible implementation for resolving a UNC path. This example uses a cache to avoid repeated referral requests, thereby improving the performance of the DFS client. A lookup in ReferralCache involves searching for an entry with DFSPathPrefix that is a complete prefix of the path being looked up. Whole path components are used in the match. Also, the ReferralCache entry with the longest match is used. For the lookup path of \MyDomain\MyDfs\MyDir\file1, if there are two ReferralCache entries, one for \MyDomain\MyDfs and another for \MyDomain\MyDfs\MyDir, the latter is the longest match. This document does not mandate that implementations adhere to this model, as long as their external behavior is consistent with the behavior described.

  1. If the path has only one path component (for example, \abc), go to step 12; otherwise, go to step 2.

  2. Look up the path in ReferralCache if a cache is being maintained. If no cache is being maintained, go to step 5.

    1. If no matching entry is found in ReferralCache, go to step 5.

    2. If an entry's TTL has expired:

    3. If an entry contains DFS link targets as indicated by RootOrLink, go to step 4; otherwise, go to step 3.

  3. [ReferralCache hit, unexpired TTL] Replace the portion of the path that matches DFSPathPrefix of the ReferralCache entry with the DFS target path of TargetHint of the ReferralCache entry. For example, if the path is \MyDomain\MyDfs\MyDir and the ReferralCache entry contains \MyDomain\MyDfs with a DFS target path of \someserver\someshare\somepath, the effective path becomes \someserver\someshare\somepath\MyDir. Go to step 8.

  4. [ReferralCache hit, unexpired TTL, RootOrLink=link]

    1. If the second component of the path is "SYSVOL" or "NETLOGON" go to step 3.

    2. Check the Interlink element of the ReferralCache entry.

      • If Interlink is set in the ReferralCache entry, then the TargetHint is in another DFS namespace. Go to step 11.

      • If Interlink is not set in the ReferralCache entry then the TargetHint is not in another DFS namespace. Go to step 3.

  5. [ReferralCache miss] [ReferralCache hit, expired TTL, RootOrLink=root] Look up the first path component in DomainCache.

    1. If no matching DomainCache entry is found, use the first path component as the host name for DFS root referral request purposes. Go to step 6.

    2. If a matching DomainCache entry is found:

      1. If DCHint is not valid, send DC referral request, as specified in section 3.1.4.2, providing "DC", BootstrapDC, UserCredentials, MaxOutputSizeff, and Path as parameters. The processing of the referral response is specified in section 3.1.5.4.2. If the referral request fails, go to step 13.

      2. If the second path component is "SYSVOL" or "NETLOGON", go to step 10.

      3. Use DCHint as host name for DFS root referral request purposes.

  6. [DFS Root referral request] Issue a DFS root referral request, as specified in section 3.1.4.2, providing "ROOT", the first path component, UserCredentials, MaxOutputSize, and Path as parameters. The processing of the referral response and/or error is as specified in section 3.1.5.4.3, which will update the ReferralCache on success. On DFS root referral request success, go to step 7. On DFS root referral request failure:

    1. If the immediately preceding processing step was step 5, this is a domain name or path. Go to step 13.

    2.  If processing of this I/O request encountered a ReferralCache hit, or one of its DFS referral requests succeeded (as would have occurred in the case of a previous Interlink - see step 11 - or a domain root referral, when entering from step 5), the path is in a DFS namespace. Go to step 14.

    3. The path is not a DFS path and no further processing is required. Go to step 12.

  7. [DFS root referral success] If the current ReferralCache entry's RootOrLink indicates root targets, go to step 3; otherwise, go to step 4.

  8. [I/O request, path fully resolved] Issue I/O operation to TargetHint of ReferralCache entry.

    1. If the I/O operation fails with STATUS_PATH_NOT_COVERED.

      • If the RootOrLink of ReferralCache entry indicates link targets, set the failure status to the last error that occurred and go to step 14.

      • If the RootOrLink of ReferralCache entry indicates root targets, the process is as specified in section 3.1.5.1. If this processing does not successfully determine a ReferralCache entry to traverse the link, set the failure status to the last error that occurred and go to step 14.

      • ReferralCache entry for the link determined successfully. Go to step 4.

    2. If the I/O operation fails with an error other than STATUS_PATH_NOT_COVERED, then the process is as specified in section 3.1.5.2. If the processing of that section specifies a new TargetHint, repeat step 8. Otherwise, set the failure status to the last error that occurred and go to step 14.

    3. If the I/O operation is successful, the process is as specified in section 3.1.5.3. Complete the I/O operation and user/application-initiated I/O request with success.

  9. [ReferralCache hit, expired TTL, RootOrLink=link] The link referral request is issued to a DFS root target of the namespace. Find the root ReferralCache entry corresponding to the first two path components, noting that this will already be in the cache due to processing that resulted in acquiring the expired link ReferralCache entry. Issue a DFS link referral request, as specified in section 3.1.4.2, providing "LINK", TargetHint of the root ReferralCache entry, UserCredentials, MaxOutputSize, and Pathf as parameters, and process the DFS referral response and/or error as specified in section 3.1.5.4.3, which will update the ReferralCache on success. If the DFS Link referral request fails, set the failure status to the last error that occurred and go to step 14. Otherwise:

    1. If the RootOrLink of the refreshed ReferralCache entry indicates DFS root targets, go to step 3.

    2. If the RootOrLink of the refreshed ReferralCache entry indicates DFS link targets, go to step 4.

  10. [sysvol referral request] Issue a sysvol referral request, as specified in section 3.1.4.2, providing 'SYSVOL', the DCHint DC of the DomainCache entry that corresponds to the domain name in the first path component, UserCredentials, MaxOutputSize, and Path as parameters. The processing of the referral response and/or error is as specified in section 3.1.5.4.4, which will update the ReferralCache on success. If the referral request is successful, go to step 3; otherwise, go to step 13.

  11. [interlink] Replace the portion of the path that matches the DFSPathPrefix of the ReferralCache entry with TargetHint. For example, if the path is \MyDomain\MyDfs\MyLink\MyDir and the referral entry contains \MyDomain\MyDfs\MyLink with a DFS target path of \someserver\someshare\somepath, the effective path becomes \someserver\someshare\somepath\MyDir. Go to step 2.

  12. [not DFS] The path does not correspond to a DFS namespace or a SYSVOL/NETLOGON share. Do not change the path, and return an implementation-defined error.<6> The user/application initiated I/O request is handled by the local operating system.

  13. [Cannot get DC for domain] The first path component is a domain name. Fail the I/O operation and user/application-initiated I/O request with the last error code that occurred before the jump to this step.

  14. [DFS path] The path is known to be in a DFS namespace, but the DFS root referral request or DFS Link referral request has failed. Complete the user/application-initiated I/O request with the error code that occurred before the jump to this step.