2.1.5.10.27 FSCTL_READ_FILE_USN_DATA

msdn link

The server provides:

  • Open: An Open of a DataFile or DirectoryFile.

  • InputBuffer: An optional array of bytes containing a READ_FILE_USN_DATA structure, as specified in [MS-FSCC] section 2.3.61.

  • InputBufferSize: The number of bytes in the InputBuffer.

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

On completion, the object store MUST return:

  • Status: An NTSTATUS code that specifies the result.

  • OutputBuffer: An array of bytes that will return a USN_RECORD_V2 or USN_RECORD_V3 as defined in [MS-FSCC] section 2.3.62.

  • BytesReturned: The number of bytes returned in OutputBuffer.

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.<110>

This operation uses the following local variables:

  • 16-bit unsigned integers: MinMajorVersionSupported, MaxMajorVersionSupported, MajorVersionToUse

  • Unicode string: LinkNameToUse

  • 32-bit unsigned integers: LinkNameLength, RecordLength

Pseudocode for the operation is as follows:

Set MinMajorVersionSupported to 2.

Set MaxMajorVersionSupported to 3.<111>

Set MajorVersionToUse to 2.

If InputBufferSize >= sizeof(READ_FILE_USN_DATA):<112>

  • If InputBuffer.MinMajorVersion > InputBuffer.MaxMajorVersion, the operation MUST be failed with STATUS_INVALID_PARAMETER.

  • If InputBuffer.MinMajorVersion > MaxMajorVersionSupported or InputBuffer.MaxMajorVersion < MinMajorVersionSupported, the operation MUST be failed with STATUS_INVALID_PARAMETER.<113>

  • If InputBuffer.MaxMajorVersion >= 3, set MajorVersionToUse to 3.

EndIf

If MajorVersionToUse == 3:

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

Else:

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

EndIf

The object store MUST choose a link name to use in constructing the reply, as shown in the following pseudocode:

  • Set LinkNameToUse to empty.

  • For each Link in Open.File.LinkList:

    • If Link.ShortName is not empty:

      • Set LinkNameToUse to Link.Name.

      • Break out of the For loop.

    • ElseIf LinkNameToUse is empty:

      • Set LinkNameToUse to Link.Name.

    • EndIf

  • EndFor

Set LinkNameLength to the length, in bytes, of LinkNameToUse.

If MajorVersionToUse == 3:

  • Set RecordLength to BlockAlign(FieldOffset(USN_RECORD_V3.FileName) + LinkNameLength, 8).

Else:

  • Set RecordLength to BlockAlign(FieldOffset(USN_RECORD_V2.FileName) + LinkNameLength, 8).

EndIf

If OutputBufferSize is less than RecordLength, the operation MUST be failed with STATUS_BUFFER_TOO_SMALL.

If MajorVersionToUse == 3, the object store MUST fill OutputBuffer with a USN_RECORD_V3 structure as follows:

  • OutputBuffer.RecordLength set to RecordLength.

  • OutputBuffer.MajorVersion set to 3.

  • OutputBuffer.MinorVersion set to 0.

  • OutputBuffer.FileReferenceNumber set to Open.File.FileId128.

  • OutputBuffer.ParentFileReferenceNumber set to Open.Link.ParentFile.FileId128.

  • OutputBuffer.Usn set to Open.File.Usn.

  • OutputBuffer.TimeStamp set to 0.

  • OutputBuffer.Reason set to 0.

  • OutputBuffer.SourceInfo set to 0.

  • OutputBuffer.SecurityId set to 0.

  • OutputBuffer.FileAttributes set to Open.File.FileAttributes, or to FILE_ATTRIBUTE_NORMAL if Open.File.FileAttributes is 0.

  • OutputBuffer.FileNameLength set to LinkNameLength.

  • OutputBuffer.FileName set to LinkNameToUse.

Else the object store MUST fill OutputBuffer with a USN_RECORD_V2 structure as follows:

  • OutputBuffer.RecordLength set to RecordLength.

  • OutputBuffer.MajorVersion set to 2.

  • OutputBuffer.MinorVersion set to 0.

  • OutputBuffer.FileReferenceNumber set to Open.File.FileId64.

  • OutputBuffer.ParentFileReferenceNumber set to Open.Link.ParentFile.FileId64.

  • OutputBuffer.Usn set to Open.File.Usn.

  • OutputBuffer.TimeStamp set to 0.

  • OutputBuffer.Reason set to 0.

  • OutputBuffer.SourceInfo set to 0.

  • OutputBuffer.SecurityId set to 0.

  • OutputBuffer.FileAttributes set to Open.File.FileAttributes, or to FILE_ATTRIBUTE_NORMAL if Open.File.FileAttributes is 0.

  • OutputBuffer.FileNameLength set to LinkNameLength .

  • OutputBuffer.FileName set to LinkNameToUse.

EndIf

The object store MUST pad OutputBuffer with trailing bytes of zeroes to bring the total number of bytes written into OutputBuffer up to RecordLength.

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

  • BytesReturned set to RecordLength.

  • Status set to STATUS_SUCCESS.