2.1.5.9.29 FSCTL_REFS_STREAM_SNAPSHOT_MANAGEMENT

The server provides:

  • Open: An Open of a DataStream.

  • InputBuffer: An array of bytes containing a single REFS_STREAM_SNAPSHOT_MANAGEMENT_INPUT_BUFFER structure indicating the management operation to be performed, as well as a Unicode name to perform the operation with. The input buffer may further contain control structures specific to each operation, as follows:

    • When InputBuffer.Operation is REFS_STREAM_SNAPSHOT_OPERATION_CREATE, section 2.1.5.9.29.1, there shall be no additional control structure.

    • When InputBuffer.Operation is REFS_STREAM_SNAPSHOT_OPERATION_LIST, section 2.1.5.9.29.2, there shall be no additional control structure.

    • When InputBuffer.Operation is REFS_STREAM_SNAPSHOT_OPERATION_QUERY_DELTAS, section 2.1.5.9.29.3, there shall be an additional control structure of type REFS_STREAM_SNAPSHOT_ QUERY_DELTAS_INPUT_BUFFER.

    • When InputBuffer.Operation is REFS_STREAM_SNAPSHOT_OPERATION_REVERT, section 2.1.5.9.29.4, there shall be no additional control structure.

    • When InputBuffer.Operation is REFS_STREAM_SNAPSHOT_OPERATION_SET_SHADOW_BTREE, section 2.1.5.9.29.5, there shall be no additional control structure.

    • When InputBuffer.Operation is REFS_STREAM_SNAPSHOT_OPERATION_CLEAR_SHADOW_BTREE, section 2.1.5.9.29.6, there shall be no additional control structure aligned to the next 8-byte boundary.

  • InputBuffer.SnapshotNameLength: The length, in bytes, of the Unicode name provided by the input buffer.

  • InputBuffer.OperationInputBufferLength: For operations requiring an additional control structure, this field indicates the length in bytes of the additional control structure.

  • InputBuffer.NameAndInputBuffer: An array of bytes containing a Unicode name and, depending on the management operation, an additional control structure.

On completion, the object store MUST return:

  • Status: An NTSTATUS code that specifies the result.

  • Depending on the NTSTATUS code returned, the object store MUST return the following structure, which is dependent on the management operation performed:

    • When the operation is REFS_STREAM_SNAPSHOT_OPERATION_LIST, the server shall return a structure of type REFS_STREAM_SNAPSHOT_LIST_OUTPUT_BUFFER. This structure shall contain:

      • OutputBuffer.EntryCount: The number of entries returned by the list query.

      • OutputBuffer.BufferSizeRequiredForQuery: The number of total bytes required to fully satisfy the list query.

      • OutputBuffer.Reserved: An array of 8 bytes set to zero.

      • OutputBuffer.Entries: An array of structures of type REFS_STREAM_SNAPSHOT_LIST_OUTPUT_BUFFER_ENTRY containing OutputBuffer.EntryCount entries. This array structure contains the following information for each entry it contains:

        • OutputBuffer.Entry[i].NextEntryOffset: The offset, in bytes, to the next entry in the array, relative to the start of the previous entry. When this value is 0, no more entries are present.

        • OutputBuffer.Entry[i].SnapshotNameLength: The length, in bytes, of the UNICODE name present in this entry.

        • OutputBuffer.Entry[i].SnapshotCreationTime: The creation time of the snapshot, represented by a  FILETIME structure stored as a 64-bit ULONGLONG.

        • OutputBuffer.Entry[i].StreamSize: The size, in bytes, of the stream represented by this entry.

        • OutputBuffer.Entry[i].StreamAllocationSize: The size, in bytes, representing the on-disk space usage of the snapshot represented by this entry.

        • OutputBuffer.Entry[i].Reserved: An array of 8 bytes set to zero.

        • OutputBuffer.Entry[i].SnapshotName: An array of OutputBuffer.Entry[i].SnapshotNameLength bytes representing the Unicode name of the snapshot represented by this entry.

    • When the operation is REFS_STREAM_SNAPSHOT_OPERATION_QUERY_DELTAS, the server shall return a structure of type REFS_STREAM_SNAPSHOT_QUERY_DELTAS_OUTPUT_BUFFER. This structure shall contain:

      • OutputBuffer.ExtentCount: The number of extents returned by the query.

      • OutputBuffer.Reserved: An array of 8 bytes set to zero.

      • An array of OutputBuffer.ExtentCount structures of type REFS_STREAM_EXTENT. This structure contains the following information for each entry:

        • OutputBuffer.Entry[i].Vcn: The VCN representing the start of the current extent.

        • OutputBuffer.Entry[i].Lcn: The LCN mapping to OutputBuffer.Entry[i].Vcn for the current extent.

        • OutputBuffer.Entry[i].Length: The length, in clusters, of the current extent.

        • OutputBuffer.Entry[i].Properties: An enum of type REFS_STREAM_EXTENT_PROPERTIES, as specified in [MS-FSCC] section 2.3.66.2.1, representing the on-disk properties of the current extent.

    • No other operation returns an output buffer.

The purpose of this FSCTL is to serve as a stream snapshot management routine for any given DataStream snapshot on any given file. The management routines handle each operation individually, and this is determined by an Operation code specified in the input buffer.

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

The server MUST validate the input and output buffer to satisfy the following requirements:

  • If the length of the input buffer is less than sizeof(REFS_STREAM_SNAPSHOT_MANAGEMENT_INPUT_BUFFER), then the operation MUST be failed with STATUS_BUFFER_TOO_SMALL.

  • If InputBuffer.OperationInputBufferLength != 0 and the length of the input buffer is less than (sizeof(REFS_STREAM_SNAPSHOT_MANAGEMENT_INPUT_BUFFER)  + QuadAlign(InputBuffer.SnapshotNameLength) + InputBuffer.OperationInputBufferLength), then the operation MUST be failed with STATUS_BUFFER_TOO_SMALL.

  • If InputBuffer.OperationInputBufferLength == 0 and the length of the input buffer is less than (sizeof(REFS_STREAM_SNAPSHOT_MANAGEMENT_INPUT_BUFFER)  + InputBuffer.SnapshotNameLength + InputBuffer.OperationInputBufferLength), then the operation MUST be failed with STATUS_BUFFER_TOO_SMALL.

  • If InputBuffer.Operation is less than REFS_STREAM_SNAPSHOT_OPERATION_CREATE or is greater than REFS_STREAM_SNAPSHOT_OPERATION_MAX, then the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • The following fields in the InputBuffer MUST be aligned. If they are not aligned, then the operation MUST be failed with STATUS_INVALID_PARAMETER.

    • InputBuffer.SnapshotNameLength MUST be 2 bytes aligned.

    • InputBuffer.OperationInputBufferLength MUST be 2 bytes aligned.

  • If the operation is either (REFS_STREAM_SNAPSHOT_OPERATION_CREATE or REFS_STREAM_SNAPSHOT_OPERATION_LIST or REFS_STREAM_SNAPSHOT_OPERATION_QUERY_DELTAS) and InputBuffer.SnapshotNameLength == 0, then the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • If the operation is REFS_STREAM_SNAPSHOT_OPERATION_CREATE and either (InputBuffer.OperationInputBufferLength != 0 or OutputBufferLength != 0), then the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • If the operation is REFS_STREAM_SNAPSHOT_OPERATION_LIST and either (InputBuffer.SnapshotNameLength == 0 or InputBuffer.OperationInputBufferLength != 0 or OutputBufferLength < sizeof(REFS_STREAM_SNAPSHOT_LIST_OUTPUT_BUFFER)), then the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • If the operation is REFS_STREAM_SNAPSHOT_OPERATION_QUERY_DELTAS and either (InputBuffer.SnapshotNameLength == 0 or InputBuffer.OperationInputBufferLength != sizeof(REFS_STREAM_SNAPSHOT_QUERY_DELTAS_INPUT_BUFFER) or OutputBufferLength < sizeof(REFS_STREAM_SNAPSHOT_QUERY_DELTAS_OUTPUT_BUFFER)), then the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • If the operation is either REFS_STREAM_SNAPSHOT_OPERATION_LIST or REFS_STREAM_SNAPSHOT_OPERATION_QUERY_DELTAS and the Open lacks FILE_READ_ATTRIBUTES access, then the operation MUST be failed with STATUS_ACCESS_DENIED.

  • If the operation is either REFS_STREAM_SNAPSHOT_OPERATION_CREATE or REFS_STREAM_SNAPSHOT_OPERATION_SET_SHADOW_BTREE or REFS_STREAM_SNAPSHOT_OPERATION_CLEAR_SHADOW_BTREE and the Open lacks FILE_WRITE_ATTRIBUTES access, then the operation MUST be failed with STATUS_ACCESS_DENIED.

  • If the operation is REFS_STREAM_SNAPSHOT_OPERATION_REVERT and the Open lacks (FILE_WRITE_ATTRIBUTES | FILE_WRITE_DATA) access, then the operation MUST be failed with STATUS_ACCESS_DENIED.