SMB_COM_TRANSACTION2:TRANS2_GET_DFS_REFERRAL

Article
07/13/2006

The client request TRANS2_GET_DFS_REFERRAL asks 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 request included the CAP_DFS capability. The TID field value of the request must be IPC$. Bit15 of the SMB_Header Flags2 field must be set to indicate that this is a UNICODE request.

Parameters for the command are encoded in SMB_COM_TRANSACTION2 command subheader fields as shown.

            Field name            Displacement      Length
                                    (bytes)        (bytes)
Client_Request
            WordCount                  0              1
            TotalDataCount             1              2
            SetupCount                 3              2
            Setup[0]                   5           Variable
ClientParameterBlockEncoding
            MaxReferralLevel           0              2
            RequestFileName            2           Variable
ResponseDataEncoding
            PathConsumed               0              2
            NumberOfReferrals          2              2
            Flags                      4              2
            Referrals[]                6           Variable
            Strings                    *           Variable
REFERRAL_LISTtype
            VersionNumber              0              2
            ReferralSize               2              2
Version1ReferralElementFormat
            ServerType                 0              2
            ReferralFlags              2              2
            Node                       4           Variable
Version2ReferralElementFormat
            ServerType                 0              2
            ReferralFlags              2              2
            Proximity                  4              4
            TimeToLive                 8              4
            DFSPathOffset              12             2
            DFSAlternatePathOffs       14             2
            NetworkAddressOffset       16             2

0	1	2	3	4	5	6	7	8	9	1 0	1	2	3	4	5	6	7	8	9	2 0	1	2	3	4	5	6	7	8	9	3 0	1

Fields

Client_Request

0 1 2 3 4 5 6 7 8 9 1
0 1 2 3 4 5 6 7 8 9 2
0 1 2 3 4 5 6 7 8 9 3
0 1
WordCount TotalDataCount SetupCount Setup[]
Client request data portion.
- WordCount
  The value is 15.
- TotalDataCount
  The value is 0.
- SetupCount
  The value is 1.
- Setup[]
  The value is TRANS2_GET_DFS_REFERRAL.
ClientParameterBlockEncoding

0 1 2 3 4 5 6 7 8 9 1
0 1 2 3 4 5 6 7 8 9 2
0 1 2 3 4 5 6 7 8 9 3
0 1
MaxReferralLevel RequestFileName
- MaxReferralLevel
  Data type: USHORT
  
  Latest referral version number understood.
- RequestFileName
  Data type: WCHAR
  
  DFS name of file for which referral is sought.
ResponseDataEncoding

0 1 2 3 4 5 6 7 8 9 1
0 1 2 3 4 5 6 7 8 9 2
0 1 2 3 4 5 6 7 8 9 3
0 1
PathConsumed Flags Referrals[] Strings
- PathConsumed
  Data type: USHORT
  
  Number of RequestFileName bytes.
- NumberOfReferrals
  Data type: USHORT
  
  Number of referrals contained in this response.
- Flags
  Data type: USHORT
  
  Additional information.
  
  Value Meaning
  
  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.
- Referrals[]
  Data type: REFERRAL_LIST
  
  Set of referrals for this file.
- Strings
  Data type: UNICODESTRING
  
  Used to hold the strings pointed to by version 2 referrals in the field Referrals.
REFERRAL_LISTtype

0 1 2 3 4 5 6 7 8 9 1
0 1 2 3 4 5 6 7 8 9 2
0 1 2 3 4 5 6 7 8 9 3
0 1
VersionNumber ReferralSize
- VersionNumber
  Data type: USHORT
  
  Version number of this referral element.
- ReferralSize
  Data type: USHORT
  
  Size of this referral element.
Version1ReferralElementFormat

0 1 2 3 4 5 6 7 8 9 1
0 1 2 3 4 5 6 7 8 9 2
0 1 2 3 4 5 6 7 8 9 3
0 1
ServerType ReferralFlags Node
- ServerType
  Data type: USHORT
  
  Type of node handling referral.
  
  Value Meaning
  
  0 Don't know
  
  1 SMB server
  
  2 Netware Server
  
  3 Domain
- ReferralFlags
  Data type: USHORT
  
  Flags that describe this referral. The expected value is listed.
  
  Value Meaning
  
  01 Strip off PathConsumed parameters before submitting.
- Node
  Data type: UNICODESTRING
  
  Name of entity to visit next.
Version2ReferralElementFormat

0 1 2 3 4 5 6 7 8 9 1
0 1 2 3 4 5 6 7 8 9 2
0 1 2 3 4 5 6 7 8 9 3
0 1
ServerType ReferralFlags Proximity TimeToLive DFSPathOffset DFSAlternatePathOffset NetworkAddressOffset
- ServerType
  Data type: USHORT
  
  Type of node handling referral.
  
  Value Meaning
  
  0 Don't know
  
  1 SMB server
  
  2 Netware Server
  
  3 Domain
- ReferralFlags
  Data type: USHORT
  
  Flags that describe this referral. The expected value is listed.
  
  Value Meaning
  
  01 Strip off PathConsumed parameters before submitting.
- Proximity
  Data type: ULONG
  
  Hint describing the proximity of this server to the client. A value of 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.
- TimeToLive
  Data type: ULONG
  
  Number of seconds for which the client can cache this referral.
- DFSPathOffset
  Data type: USHORT
  
  Offset, in bytes from the beginning of this referral, of the DFS path that matched the PathConsumed bytes of the RequestFileName field.
- DFSAlternatePathOffset
  Data type: USHORT
  
  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 field.
- NetworkAddressOffset
  Data type: USHORT
  
  Offset, in bytes from the beginning of this referral, of the entity to visit next.

Value	Meaning
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.

Value	Meaning
0	Don't know
1	SMB server
2	Netware Server
3	Domain

Value	Meaning
01	Strip off PathConsumed parameters before submitting.

Value	Meaning
0	Don't know
1	SMB server
2	Netware Server
3	Domain

Value	Meaning
01	Strip off PathConsumed parameters before submitting.

Remarks

The server response is a list of referrals which inform the client where it should resubmit the request to obtain access to the file. The PathConsumed field in the response indicates to the client how many characters of the RequestFileName value 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 the path 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. The MaxReferralLevel field indicates to the server the latest version of referral which the client can digest. Because each referral has a uniform element, MaxReferralLevel is advisory only.

The CIFS protocol imposes no referral selection policy.

SMB_COM_TRANSACTION2:TRANS2_GET_DFS_REFERRAL

Fields

Remarks

See Also

Additional resources