Share via

3.2.4.6 Application Requests Reading from a File or Named Pipe

  • Article

The application provides:

  • A handle to the Open identifying a file or named pipe.

  • The offset from which to read data.

  • The number of bytes to read.

  • The minimum number of bytes it would like to be read (optional).

  • The buffer to receive the data that is read.

  • UnbufferedRead, A Boolean flag indicating whether the read has to be unbuffered (optional).

  • CompressRead, A Boolean flag indicating that the response is eligible for compression (optional).

If the handle is invalid, or if no Open referenced by the handle is found, the client MUST return an implementation-specific error code. If the handle is valid and Open is found, the client MUST proceed as follows.

For the specified Open, the client MUST select a connection as specified in section 3.2.4.1.7. If no connection is available, the client MUST fail the read operation.

Otherwise, the client initializes an SMB2 READ Request following the syntax specified in section 2.2.19. The SMB2 header MUST be initialized as follows:

  • The Command field is set to SMB2 READ.

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

  • The TreeId field is set to Open.TreeConnect.TreeConnectId.

The SMB2 READ Request MUST be initialized as follows:

  • If Connection.Dialect is "3.0.2" or "3.1.1", and if the application-supplied UnbufferedRead is TRUE, the SMB2_READFLAG_READ_UNBUFFERED bit in the Flags field MUST be set.

  • If Connection.Dialect is "3.1.1", IsCompressionSupported is TRUE, Connection.CompressionIds is not empty, and the application-supplied CompressRead or TreeConnect.CompressData is TRUE, the SMB2_READFLAG_REQUEST_COMPRESSED bit in the Flags field MUST be set.

  • The Length field is set to the number of bytes the application requested to read.

  • The Offset field is set to the offset within the file, in bytes, at which the application requested the read to start.

  • The client SHOULD<151> set MinimumCount field to the value that is provided by the application. If no value is provided by the application, the client SHOULD set this field to 0.

  • The FileId field is set to Open.FileId.

  • The Padding field SHOULD be set to 0x50, which is the default padding of an SMB2 READ Response.

If the number of bytes to read exceeds Connection.MaxReadSize, the client MUST split the read up into separate read operations no larger than Connection.MaxReadSize. The client MAY send these separate reads in any order.<152>

If a client requests reading from a file, Connection.Dialect is not "2.0.2", and if Connection.SupportsMultiCredit is TRUE, the CreditCharge field in the SMB2 header MUST be set to ( 1 + (Length – 1) / 65536 ).

If the Connection is established in RDMA mode and the size of any single operation exceeds an implementation-specific threshold <153>, and if Open.TreeConnect.Session.SigningRequired and Open.TreeConnect.Session.EncryptData are both FALSE, then the interface in [MS-SMBD] section 3.1.4.3 Register Buffer MUST be used to register the buffer provided by the calling application on the Connection with write permissions, which will receive the data to be read. The returned list of SMB_DIRECT_BUFFER_DESCRIPTOR_V1 structures MUST be stored in Request.BufferDescriptorList. The following fields of the request MUST be initialized as follows:

  • If Connection.Dialect is "3.0.2" or "3.1.1" and processing of received remote invalidation is supported as specified in [MS-SMBD] section 3.1.5.8, the Channel field of the request SHOULD be set to SMB2_CHANNEL_RDMA_V1_INVALIDATE. Otherwise, the Channel field of the request MUST be set to SMB2_CHANNEL_RDMA_V1.

  • The returned list of SMB_DIRECT_BUFFER_DESCRIPTOR_V1 structures MUST be added to the Buffer field of the request.

  • The ReadChannelInfoOffset MUST be set to the offset of the added list from the beginning of the SMB2 header.

  • The ReadChannelInfoLength MUST be set to the length of the added list.

Otherwise, the following fields of the request MUST be initialized as follows:

  • If Connection.Dialect belongs to the SMB 3.x dialect family:

    • The Channel field MUST be set to SMB2_CHANNEL_NONE.

    • The ReadChannelInfoOffset field MUST be set to 0.

    • The ReadChannelInfoLength field MUST be set to 0.

  • The first byte of the Buffer field MUST be set to 0.

The MessageId field in the SMB2 header is set as specified in section 3.2.4.1.3, and the request is sent to the server.