3.1.4.2 Sending a DFS Referral Request to the Server
This interface is only used internally by the DFS client to send a DFS referral request to a specific server. The caller provides the following:
-
Type: A string identifying the type of the referral request.
-
HostName: The name of the server from which to query referrals.
-
UserCredentials: An opaque implementation-specific entity that identifies the credentials to be used when authenticating to the remote server.
-
MaxOutputSize: The maximum output buffer response size, in bytes.
-
Path: The path for which referral information is to be queried.
The client MUST initiate a server session with the SMB server, as specified in [MS-CIFS] section 3.4.4.7, by passing HostName and UserCredentials as input parameters and receiving an opaque ClientGenericContext, as specified in [MS-CIFS] section 3.4.
The client MUST verify the local configuration on extended referrals in an implementation-specific manner<8>, and MUST also query the server’s extended referral capability by invoking the event as specified in [MS-CIFS] section 3.4.4.12.
If both the tests return TRUE, the client MUST obtain the name of the site to which it belongs in an implementation-specific manner<9> and query the DFS referral, as specified in [MS-CIFS] section 3.4.4.9, by passing ClientGenericContextf, HostName, UserCredentials, and MaxOutputSize values, an updated Path according to the format of the RequestFileName in the table that follows, the name of the site, and an appropriate MaxReferralLevel value corresponding to the Type as specified in the table below. If any of the tests returns FALSE, the client MUST then query the DFS referral, as specified in [MS-CIFS] section 3.4.4.9, by passing ClientGenericContextf, HostName, UserCredentials, and MaxOutputSize values, an updated Path according to the format of the RequestFileName in the table that follows, and an appropriate MaxReferralLevel value corresponding to the Type as specified in the following table:
|
Type |
RequestFileName |
MaxReferralLevel |
|
DOMAIN |
An empty string (containing just the null terminator). |
3 or higher |
|
DC |
"\<domain>" or "<domain>", where <domain> is a domain name that can be in either NetBIOS or fully qualified domain name forms. |
3 or higher |
|
SYSVOL |
Either "\<domain>\SYSVOL" or "\<domain>\NETLOGON", where <domain> is a domain name that can be in either NetBIOS or fully qualified domain name forms. |
No restriction |
|
ROOT |
Of the form either "\<domain>\<dfsname>" or "\<server>\<dfsname>", where <domain> is the name of the domain that hosts the DFS namespace, <dfsname> is the name of a DFS namespace, and <server> is a DFS root target host name. |
No restriction |
|
LINK |
Of the form either "\<domain>\<dfsname>\<linkpath>" or "\<server>\<dfsname>\<linkpath>", where <domain> is the name of the domain that hosts the DFS namespace, <dfsname> is the name of a DFS namespace, <server> is a DFS root target host name, <linkpath> is a path that may have a DFS link. |
No restriction |
The client MUST wait synchronously for the completion of the referral request and pass the referral response received from the server to the caller. If the request fails with STATUS_DFS_UNAVAILABLE, the client MUST return the same error code to the caller.
The client MUST validate that the returned referral response is properly formed, (section 2.2.5). If the response is ill-formed, the client MUST fail the referral request and return the error code STATUS_INVALID_NETWORK_RESPONSE to the caller.
