2.1.5.10.15 FSCTL_GET_RETRIEVAL_POINTERS

  • Article

The server provides:

  • Open: An Open of a DataStream or DirectoryStream.

  • StartingVcnBuffer: An array of bytes containing a STARTING_VCN_INPUT_BUFFER as described in [MS-FSCC] section 2.3.31.

  • OutputBufferSize: The maximum number of bytes to return in OutputBuffer.

On completion, the object store MUST return:

  • OutputBuffer: An array of bytes that will return a RETRIEVAL_POINTERS_BUFFER as defined in [MS-FSCC] section 2.3.32.

  • BytesReturned: The number of bytes returned to the caller.

  • Status: An NTSTATUS code that specifies the result.

Pseudocode for the operation is as follows:

  • Phase 1 -- Verify Parameters

  • If the size of StartingVcnBuffer is less than sizeof (STARTING_VCN_INPUT_BUFFER), the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • If OutputBufferSize is smaller than sizeof(RETRIEVAL_POINTERS_BUFFER), the operation MUST be failed with STATUS_BUFFER_TOO_SMALL.

  • If StartingVcnBuffer.StartingVcn is negative, the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • If StartingVcnBuffer.StartingVcn is greater than or equal to Open.Stream.AllocationSize divided by Open.File.Volume.ClusterSize, the operation MUST be failed with STATUS_END_OF_FILE.

  • Phase 2 -- Locate and copy the extents into OutputBuffer.

  • Find the first Extent in Open.Stream.ExtentList where Extent.NextVcn is greater than StartingVcnBuffer.StartingVcn.

  • Set OutputBuffer.StartingVcn to the previous element's NextVcn. If the element is the first one in Open.Stream.ExtentList, set OutputBuffer.StartVcn to zero.

  • Copy as many EXTENTS elements from Open.Stream.ExtentList starting with Extent as will fit into the remaining space in OutputBuffer, at offset OutputBuffer.Extents.

  • Set OutputBuffer.ExtentCount to the number of EXTENTS elements copied.

  • Upon successful completion of the operation, the object store MUST return:

    • BytesReturned set to the number of bytes written to OutputBuffer.

    • Status set to STATUS_SUCCESS if all of the elements in Open.Stream.ExtentList were copied into OutputBuffer.Extents, else STATUS_BUFFER_OVERFLOW.