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<7>, 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 construct the REQ_GET_DFS_REFERRAL_EX request, as specified in section 2.2.3, with the following parameters:
MaxReferralLevel is set to the corresponding Type as specified in the following table.
RequestFlags is set to 1.
RequestFileName is set to Path.
SiteName is set in an implementation-specific manner.<8>
If any of the tests return FALSE, the client MUST construct a REQ_GET_DFS_REFERRAL request, as specified in section 2.2.2, with the following parameters:
MaxReferralLevel is set to the corresponding Type as specified in the following table.
RequestFileName is set to Path.
The client MUST query the DFS referral, as specified in [MS-CIFS] section 3.4.4.9, by passing ClientGenericContext, HostName, UserCredentials, MaxOutputSize, the REQ_GET_DFS_REFERRAL_EX or REQ_GET_DFS_REFERRAL structure as the input buffer, and the FSCTL code set to FSCTL_DFS_GET_REFERRALS, if the input buffer is an REQ_GET_DFS_REFERRAL, or FSCTL_DFS_GET_REFERRALS_EX, if the input buffer is an REQ_GET_DFS_REFERRAL_EX.
|
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 can 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.