2.1.5.10.38 FSCTL_SET_SPARSE

  • Article

The server provides:

  • Open: An Open of a DataStream.

  • InputBufferSize: The byte count of the InputBuffer.

  • InputBuffer: A buffer of type FILE_SET_SPARSE_BUFFER as defined in [MS-FSCC] section 2.3.83.

On completion, the object store MUST return:

  • Status: An NTSTATUS code that specifies the result.

Support for this operation is optional. If the object store does not implement this functionality, the operation MUST be failed with STATUS_INVALID_DEVICE_REQUEST.<138><139>

Pseudocode for the operation is as follows:

  • If Open.Stream.StreamType != DataStream, the object store MUST fail the operation and return STATUS_INVALID_PARAMETER.

  • If Open.File.Volume.IsReadOnly is TRUE, the object store MUST return STATUS_MEDIA_WRITE_PROTECTED.

  • If Open.GrantedAccess.FILE_WRITE_DATA is FALSE and Open.GrantedAccess.FILE_WRITE_ATTRIBUTES is FALSE, the operation MUST be failed with STATUS_ACCESS_DENIED.

  • The object store MUST post a USN change as specified in section 2.1.4.11 with File equal to File, Reason equal to USN_REASON_BASIC_INFO_CHANGE, and FileName equal to Open.Link.Name. If InputBuffer.SetSparse is TRUE:

    • The object store MUST set Open.Stream.IsSparse to TRUE.

    • The object store MUST set Open.File.FileAttributes.FILE_ATTRIBUTE_SPARSE_FILE to TRUE, indicating that at least one stream of the file is sparse.

  • Else

    • For each Extent in Open.Stream.ExtentList:

      • If Extent.LCN is un-allocated as specified in [MS-FSCC] 2.3.32.1:

        • The object store MUST fully allocate the Extent. If the space cannot be allocated, then the operation MUST be failed with STATUS_DISK_FULL. The object store is not required to revert any allocations performed during the operation.

      • EndIf

    • EndFor

    • The object store MUST set Open.Stream.IsSparse to FALSE.

    • If there does not exist an ExistingStream in Open.File.StreamList such that ExistingStream.IsSparse is TRUE:

      • The object store MUST set Open.File.FileAttributes.FILE_ATTRIBUTE_SPARSE_FILE to FALSE, indicating that no streams of the file are sparse.

    • EndIf

  • EndIf

  • Set Open.File.PendingNotifications.FILE_NOTIFY_CHANGE_ATTRIBUTES to TRUE.

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

    • Status set to STATUS_SUCCESS.