3.2.4.3 Application Requests Opening a File

  • Article

To open a file on a remote share, the application provides the following:

  • A handle to the TreeConnect representing the share in which the file to be opened exists.

  • The path name of the file being opened, as a DFS pathname for a DFS share, or relative to the TreeConnect for a non-DFS share.

  • A handle to the Session representing the security context of the user opening the file.

  • The required access for the open, as specified in section 2.2.13.1.

  • The sharing mode for the open, as specified in section 2.2.13.

  • The create options to be applied for the open, as specified in section 2.2.13.

  • The create disposition for the open, as specified in section 2.2.13.

  • The file attributes for the open, as specified in section 2.2.13.

  • The impersonation level for the open, as specified in section 2.2.13 (optional).

  • The security flags for the open, as specified in section 2.2.13 (optional).

  • The requested oplock level or lease state for the open, as specified in section 2.2.13 (optional).

  • As outlined in subsequent sections, the application can also provide a series of create contexts, as specified in section 2.2.13.2.

The client MUST verify the TreeConnect and Session handles. If the handles are invalid, or if no TreeConnect referenced by the tree connect handle is found, or if no Session referenced by the session handle is found, the client MUST return an implementation-specific error code locally to the calling application.

The client MUST conform to the specification in [MS-FSCC] section 2.1.5 for the application-supplied path name.

If the handles are valid and a TreeConnect and Session are found, the caller MUST ensure that the supplied TreeConnect is valid within the Session. TreeConnect.Session MUST match the Session.

The client MUST use the Connection referenced by Session.Connection to send the request to the server.

If the client implements the SMB 2.1 dialect or SMB 3.x dialect family and Connection.SupportsFileLeasing is TRUE, the client MUST search the GlobalFileTable for an entry matching one of the following:

  • The application-supplied PathName if TreeConnect.IsDfsShare is TRUE.

  • The concatenation of Connection.ServerName, TreeConnect.ShareName, and the application-supplied PathName, joined with pathname separators (example: server\share\path), if TreeConnect.IsDfsShare is FALSE.

If an entry is not found, a new File entry MUST be created and added to the GlobalFileTable and a File.LeaseKey,<137> as specified in section 3.2.1.5, MUST be assigned to the entry.<138> File.OpenTable MUST be initialized to an empty table and File.LeaseState MUST be initialized to SMB2_LEASE_NONE.

If an entry is found, the client SHOULD<139> include a lease context with the existing lease key, lease state, and epoch.<140>

If Connection.Dialect belongs to the SMB 3.x dialect family, Connection.SupportsDirectoryLeasing is TRUE, and the file being opened is not the root of the share, the client MUST search the GlobalFileTable for the parent directory of the file being opened.  The name of the parent directory is obtained by removing the last component of the path used to search the GlobalFileTable above. If an entry for the parent directory is not found, a new File entry MUST be created for it and added to the GlobalFileTable and a File.LeaseKey,<141> as specified in section 3.2.1.5, MUST be assigned to the entry. File.OpenTable MUST be initialized to an empty table and File.LeaseState MUST be initialized to SMB2_LEASE_NONE.

If the client accesses a file through multiple paths, such as using different server names or share names or parent directory names, it will create multiple File elements, and therefore multiple File.LeaseKeys for the same remote file. This loses the performance benefits of sharing cache state across all Opens of the same file and can cause additional lease breaks to be generated, as actions by a client through one path will affect caching by that client through other paths. However, the impact is a matter of performance; cache correctness is preserved. If the client accesses the same path across multiple opens, the client will use the same File element and therefore the same File.LeaseKey is used.

The client MUST construct an SMB2 CREATE Request using the syntax specified in section 2.2.13. The SMB2 header MUST be initialized as follows:

  • The Command field is set to SMB2 CREATE.

  • The MessageId field is set as specified in section 3.2.4.1.3.

  • The SessionId field is set to TreeConnect.Session.SessionId.

  • The TreeId field is set to TreeConnect.TreeConnectId.

  • If TreeConnect.IsDfsShare is TRUE, the SMB2_FLAGS_DFS_OPERATIONS flag is set in the Flags field.

The SMB2 CREATE Request MUST be initialized as follows:

  • The SecurityFlags field is set to 0.

  • The ImpersonationLevel field is set to the application-provided impersonation level. If the application did not provide an impersonation level, the client sets the ImpersonationLevel to Impersonation.

  • The client sets the DesiredAccess field to the value that is provided by the application.

  • The client sets the FileAttributes field to the attributes that are provided by the application.

  • The client sets the ShareAccess field to the sharing mode that is provided by the application.

  • The client sets the CreateDisposition field to the create disposition that is provided by the application.

  • The client sets the CreateOptions field to the create options that are provided by the application.

§ The RequestedOplockLevel field is set as below:

§ If CreateOptions includes FILE_DIRECTORY_FILE,

§ If Connection.SupportsDirectoryLeasing is TRUE, the client SHOULD set RequestedOplockLevel field to SMB2_OPLOCK_LEVEL_LEASE.

§ Otherwise, RequestedOplockLevel field is set to SMB2_OPLOCK_LEVEL_ NONE.

§ Otherwise,

§ If the filename is stream name as defined in [MS-FSCC] section 2.1.5.3, RequestedOplockLevel field is set to SMB2_OPLOCK_LEVEL_NONE.

§ Otherwise, if Connection.SupportsFileLeasing is TRUE, the client SHOULD<142> set RequestedOplockLevel field to SMB2_OPLOCK_LEVEL_LEASE.

§ Otherwise, if the oplock level requested by the application is SMB2_OPLOCK_LEVEL_NONE or SMB2_OPLOCK_LEVEL_II or SMB2_OPLOCK_LEVEL_BATCH, the client MUST set RequestedOplockLevel field to the oplock level that is requested by the application.

§ Otherwise, RequestedOplockLevel field is set to an implementation-specific oplock level.<143>

  • The client copies the application-supplied path into the Buffer, and sets the NameLength to the length, in bytes, of the path and the NameOffset to the offset, in bytes, to the path from the beginning of the SMB2 header.

  • The client copies any provided create contexts into the Buffer after the file name, and sets the CreateContextsOffset to the offset, in bytes, to the create contexts from the beginning of the SMB2 header and sets the CreateContextsLength to the length, in bytes, of the array of create contexts. If there are no provided create contexts, CreateContextsLength and CreateContextsOffset MUST be set to 0.

This request MUST be sent to the server. The response from the server MUST be processed as described in section 3.2.5.7.