Share via

3.2.4.2 Application Requests a Connection to a Share

  • Article

The application provides the following:

  • ServerName: The name of the server to connect to.

  • ShareName: The name of the share to connect to.

  • UserCredentials: An opaque implementation-specific entity that identifies the credentials to be used when authenticating to the remote server.

  • TransportIdentifier: An optional implementation-specific identifier for the transport on which the connection is to be established.

  • SpecifiedDialects: An optional list of dialects to be negotiated. If provided, this MUST be one or more values as specified in Dialects field of SMB2 NEGOTIATE Request in section 2.2.3.

  • ClusterReconnect: An optional Boolean that, if set to TRUE, specifies that the client is reconnecting to the cluster share specified by ShareName.

  • SyncRedirect: An optional Boolean that, if set to TRUE, specifies that the client supports synchronous share level redirection.

  • RemotedIdentity: An optional Boolean that, if set to TRUE, specifies that the client is establishing a remoted identity for accessing the share using additional provided identity values.

  • Guid: An optional client GUID.

Upon successful completion, the client MUST return an existing or newly constructed Session handle (section 3.2.1.3), an existing or newly constructed TreeConnect handle, and the share type (section 3.2.1.4) to the caller.

The request to connect to a server could be either explicit (the application requests the connection directly) or implicit (the application requests opening a file with a network path including server and share). In either case, the client MUST follow the steps described in the following flow chart.<118> For the implicit case, any error returned from the connection attempt MUST be returned as the error code for the operation that initiated the implicit connection attempt. For the explicit case, any error returned from the connection attempt MUST be returned to the calling application.

The client SHOULD search the ConnectionTable and attempt to find an SMB2 connection where:

  • Connection.ServerName matches the application-supplied ServerName.

  • If provided by the application, the highest dialect in the SpecifiedDialects matches the Connection.Dialect.

  • If provided by the application, Guid matches the Connection.ClientGuid.

If a connection is found, the client SHOULD use the existing connection. For each existing connection to the target server, the client MUST search through Connection.SessionTable for a Session that satisfies the client implementation requirements for session reuse. <119>

  • If UserCredentials, the credentials to be used for the application request, do not match Session.UserCredentials, those used in establishing the existing session, the session MUST NOT be reused.

  • For operations on an existing Open, the client MUST select the same session that was used to establish the Open.

  • The client SHOULD attempt to minimize redundant sessions to the same server.

  • The client MAY establish multiple sessions to the same server by the same security context.

  • If a new session is being established, the client MAY reuse an existing connection such that multiple sessions are multiplexed on the same connection. If not reusing an existing connection, the client can establish a new connection for the new session.

  • The client MUST synchronize simultaneous application requests, as needed, if an existing session with the same user credential is currently being established.

If a matching session is found, the client MUST search through Session.TreeConnectTable to find a matching tree connection to the share. If a tree connection is found, the client MUST use the existing tree connection, and no additional steps are required to be performed. If a matching tree connection is not found, the client MUST proceed with establishing a tree connection to the share as described in section 3.2.4.2.4.

If a matching session is not found, the client MAY<120> either attempt to establish the session on the existing connection, or establish a new connection. If the client is reusing an existing connection, the client MUST perform the following steps:

  1. Authenticate to the server as described in section 3.2.4.2.3.

  2. Establish a new tree connection to the target share as described in section 3.2.4.2.4.

Otherwise, the client MUST perform the following steps:

  1. Establish a new connection as described in section 3.2.4.2.1.

  2. Negotiate the protocol as described in section 3.2.4.2.2.

  3. Authenticate to the server as described in section 3.2.4.2.3.

  4. Establish a new tree connection to the target share as described in section 3.2.4.2.4.

The client MUST follow the steps outlined in this chart

Figure 4: The client MUST follow the steps outlined in this chart