3.3.5.15.8 Handling a Pass-Through Operation Request

  • Article

Pass-through requests are I/O Control requests and File System Control (FSCTL) requests with a CtlCode value that is not specified in section 2.2.31. As noted in section 3.3.5.15, the server MUST fail I/O Control requests with STATUS_NOT_SUPPORTED.

Pass-through FSCTL requests fall further into two types, those for which a CtlCode value matches an FSCTL function number defined in [MS-FSCC] section 2.3, and those that do not. When the latter type of pass-through request does not meet the private FSCTL requirements of [MS-FSCC] section 2.3, the server MUST NOT pass the request to the underlying object store and MUST fail the request by sending a response of STATUS_NOT_SUPPORTED.

Otherwise, when the server receives a pass-through FSCTL request, the server SHOULD<385> pass it through to the underlying object store.

The server MUST pass the following to the underlying object store: CtlCode, the input buffer described by InputOffset and InputCount, the output buffer described by OutputOffset and OutputCount, the MaxOutputResponse as the maximum output buffer size, in bytes, for the response, and MaxInputResponse as the maximum input buffer size, in bytes, for the response. Where the CtlCode value matches an FSCTL function number defined in [MS-FSCC], the server SHOULD verify that the above buffers and sizes conform to the requirements of the corresponding structures defined in [MS-FSCC] section 2.3, and use the FileId from the SMB2 IOCTL request to obtain the handle described in [MS-FSCC] section 2.3 to pass to the object store. Where the CtlCode value is not defined in [MS-FSCC], the server SHOULD<386> ensure that the other requirements for private FSCTLs defined in [MS-FSCC] are met.

If the underlying object store returns a failure, the server MUST fail the request and send a response with an error code, as specified in [MS-ERREF] section 2.2.

Note that a successful FSCTL pass-through request could return 0 bytes of output buffer data, and have OutputCount set to 0. Similarly, it is possible for a valid FSCTL pass-through request to send 0 bytes of input buffer data, depending on the requirements of the FSCTL.

If the operation succeeds, the server MUST then construct an SMB2 IOCTL Response following the syntax specified in section 2.2.32, with the following values:

  • CtlCode MUST be set to the CtlCode of the request.

  • FileId.Persistent MUST be set to Open.DurableFileId. FileId.Volatile MUST be set to Open.FileId.

  • InputOffset SHOULD be set to the offset, in bytes, from the beginning of the SMB2 header to the Buffer[] field of the response.

  • InputCount MUST be set to the number of input bytes the object store is returning to the client.

  • If the object store is returning output data to the client, OutputOffset MUST be set to InputOffset + InputCount, rounded up to a multiple of 8. Otherwise, OutputOffset SHOULD<387> be set to zero.

  • The server MUST set the OutputCount to the actual number of bytes returned by the underlying object store in the output buffer.

  • Flags MUST be set to zero.

  • The server MUST copy the input and output response bytes into the ranges in Buffer described by InputOffset/InputCount and OutputOffset/OutputCount.

The response MUST be sent to the client.