The client sends this request to ask the server to convert RequestFilename into an alternate name for this file. This request can be sent to the server if the server response to the NEGOTIATE SMB included the CAP_DFS capability. The TID of the request must be IPC$. Bit15 of Flags2 in the SMB header must be set, indicating this is a UNICODE request.
| Client Request ========================== |
Description ========================================= |
| WordCount | 15 |
| TotalDataCount | 0 |
| SetupCount | 1 |
| Setup[0] | TRANS2_GET_DFS_REFERRAL |
| Parameter Block Encoding ========================== |
Description ========================================= |
| USHORT MaxReferralLevel | Latest referral version number understood |
| WCHAR RequestFileName; | DFS name of file for which referral is sought |
| Response Data Block ========================== |
Description ========================================= |
| USHORT PathConsumed; | Number of RequestFilename bytes client |
| USHORT NumberOfReferrals; | Number of referrals contained in this response |
| USHORT Flags; | bit0 - The servers in Referrals are capable of fielding TRANS2_GET_DFS_REFERRAL. bit1 - The servers in Referrals should hold the storage for the requested file. |
| REFERRAL_LIST Referrals[] | Set of referrals for this file |
| UNICODESTRINGE Strings | Used to hold the strings pointed to by Version 2 Referrals in referrals. |
The server response is a list of Referrals which inform the client where it should resubmit the request to obtain access to the file. PathConsumed in the response indicates to the client how many characters of RequestFilename have been consumed by the server. When the client chooses one of the referrals to use for file access, the client may need to strip the leading PathConsumed characters from the front of RequestFileName before submitting the name to the target server. Whether or not the pathname should be trimmed is indicated by the individual referral as detailed below.
flags indicates how this referral should be treated. If bit0 is clear, any entity in the Referrals list holds the storage for RequestFileName. If bit0 is set, any entity in the Referrals list has further referral information for RequestFilename – a TRANS2_GET_DFS_REFERRAL request should be sent to an entity in the Referrals list for further resolution.
The format of an individual referral contains version and length information allowing the client to skip referrals it does not understand. MaxReferralLevel indicates to the server the latest version of referral which the client can digest. Since each referral has a uniform element, MaxReferralLevel is advisory only. Each element in Referrals has this envelope:
| REFERRAL_LIST element ====================================================================== |
|
| USHORT VersionNumber | Version of this referral element |
| USHORT ReferralSize | Size of this referral element |
The following referral element versions are defined:
| Version 1 Referral Element Format ====================================================================== |
|
| USHORT ServerType | Type of Node handling referral: 0 - Don't know 1 - SMB Server 2 - Netware Server 3 - Domain |
| USHORT ReferralFlags | Flags which describe this referral: 01 - Strip off PathConsumed characters before submitting RequestFileName to Node |
| UNICODESTRING Node | Name of entity to visit next |
| Version 2 Referral Element Format ====================================================================== |
|
| USHORT ServerType | Type of Node handling referral: 0 - Don't know 1 - SMB Server 2 - Netware Server 3 - Domain |
| USHORT ReferralFlags | Flags which describe this referral: 01 - Strip off PathConsumed characters before submitting RequestFileName to Node |
| ULONG Proximity | A hint describing the proximity of this server to the client. 0 indicates the closest, higher numbers indicate increasingly "distant" servers. The number is only relevant within the context of the servers listed in this particular SMB. |
| ULONG TimeToLive | Number of seconds for which the client can cache this referral. |
| USHORT DfsPathOffset | Offset, in bytes from the beginning of this referral, of the DFS Path that matched PathConsumed bytes of the RequestFileName. |
| USHORT DfsAlternatePathOffset | Offset, in bytes from the beginning of this referral, of an alternate name (8.3 format) of the DFS Path that matched PathConsumed bytes of the RequestFileName. |
| USHORT NetworkAddressOffset | Offset, in bytes from the beginning of this referral, of the entity to visit next. |
The CIFS protocol imposes no referral selection policy.