3.2.4.5 Application Requests Opening an Existing File

  • Article

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

  • The Client.TreeConnect representing the share in which the file to be opened exists.

  • The pathname of the file being opened, relative to Client.TreeConnect.ShareName.

  • The Client.Session representing the security context of the user opening the file.

  • The requested access mode (read, write, and so on).

  • The share access for the open.

  • The create disposition for the open.

  • An optional set of create options for the open.

  • An optional Boolean indicating whether the attributes and time stamps of the file are to be returned in the response.

  • An optional Boolean indicating whether the total length of the file's extended attributes is to be returned in the response.

  • A Boolean indicating whether or not the parent directory of the target is to be opened.

  • An optional requested impersonation level.

  • The security flags.

  • An optional allocation size.

  • An optional timeout value.

  • An optional security descriptor.

  • The request for an exclusive or batch OpLock, if any.<204>

To open the file, the client can issue one of the following command requests:

  • SMB_COM_OPEN (section 2.2.4.3) (deprecated)

    The client MUST construct an SMB_COM_OPEN Request (section 2.2.4.3.1) message. This command provides basic Open semantics.

  • SMB_COM_OPEN_ANDX (section 2.2.4.41) (deprecated)

    The client MUST construct an SMB_COM_OPEN_ANDX Request (section 2.2.4.41.1) message. In addition to basic Open semantics, SMB_COM_OPEN_ANDX provides:

    • AndX chaining.

    • The ability to request detailed information regarding the opened file.

    • The ability to select the file to be opened based upon the file attributes, as well as the ability to set the file attributes if the file does not exist and needs to be created.

    • The ability to set or reset the creation time of the file.

    • The disposition action to take based on the existence of the target file.

  • TRANS2_OPEN2 (section 2.2.6.1)

    The client MUST construct an SMB_COM_TRANSACTION2 (section 2.2.4.46) transaction request, to transport the TRANS2_OPEN2 transaction request. The client MUST construct a TRANS2_OPEN2 Request (section 2.2.6.1.1). In addition to basic Open semantics, TRANS2_OPEN2 provides:

    • The ability to set extended attribute (EA) name/value pairs.

    • The ability to set or reset the creation time of the file.

    • The ability to specify an initial allocation for newly opened or overwritten files.

    • The disposition action to take based on the existence of the target file.

  • NT_TRANSACT_CREATE (section 2.2.7.1)

    The client MUST construct an SMB_COM_NT_TRANSACT (section 2.2.4.62) transaction request,to transport the NT_TRANSACT_CREATE transaction request. The client MUST construct an NT_TRANSACT_CREATE Request (section 2.2.7.1.1). In addition to basic Open semantics, NT_TRANSACT_CREATE provides:

    • The ability to specify a path relative to a subdirectory within the share indicated by the TID.

    • The ability to specify an initial allocation for newly opened or overwritten files.

    • The disposition action to take based on the existence of the target file.

  • SMB_COM_NT_CREATE_ANDX (section 2.2.4.64)

    The client MUST construct an SMB_COM_NT_CREATE_ANDX Request (section 2.2.4.64.1) message. In addition to basic Open semantics, SMB_COM_NT_CREATE_ANDX provides:

    • AndX chaining.

    • The ability to open or create a directory.

    • The ability to specify a path relative to a subdirectory within the share indicated by the TID.

    • The ability to specify an initial allocation for newly opened or overwritten files.

    • The disposition action to take based on the existence of the target file.

      The SMB_COM_NT_CREATE_ANDX is the most comprehensive (and, therefore, the most complex) of the open commands.

Any of the commands or subcommands listed above can be used to open a file. Directories, named pipes, and devices can also be opened. Most of these commands provide the option to create a file if it does not already exist, or to overwrite or append to the file if it does exist. For SMB_COM_OPEN (section 2.2.4.3), SMB_COM_OPEN_ANDX (section 2.2.4.41), and TRANS2_OPEN2 (section 2.2.6.1) commands, the client MUST construct the AccessMode field of the request by translating the input parameters as follows:

Input parameter

Value(s)

AccessMode bit field

Value

Access mode

Only read access

AccessMode.AccessMode

0

Access mode

Only write access

AccessMode.AccessMode

1

Access mode

Read and write access

AccessMode.AccessMode

2

Access mode

execute

AccessMode.AccessMode

3

Share Access

0

AccessMode.SharingMode

1

Share Access

FILE_SHARE_READ

AccessMode.SharingMode

2

Share Access

FILE_SHARE_WRITE

AccessMode.SharingMode

3

Share Access

FILE_SHARE_DELETE

AccessMode.SharingMode

4

Create Options

FILE_SEQUENTIAL_ONLY = 0 and FILE_RANDOM_ACCESS = 0

AccessMode.ReferenceLocality

0

Create Options. FILE_SEQUENTIAL_ONLY

1

AccessMode.ReferenceLocality

1

Create Options. FILE_RANDOM_ACCESS

1

AccessMode.ReferenceLocality

2 or 3

Create Options.FILE_NO_INTERMEDIATE_BUFFERING

0

AccessMode.CacheMode

0

Create Options.FILE_NO_INTERMEDIATE_BUFFERING

1

AccessMode.CacheMode

1

Create Options. FILE_WRITE_THROUGH

0

AccessMode.WritethroughMode

0

Create Options. FILE_WRITE_THROUGH

1

AccessMode.WritethroughMode

1

The request MUST be sent to the server as described in section 3.2.4.1.