USN_RECORD_V4 structure (winioctl.h)
Contains the information for an update sequence number (USN) change journal version 4.0 record. The version 2.0 and 3.0 records are defined by the USN_RECORD_V2 (also called USN_RECORD) and USN_RECORD_V3 structures respectively.
Syntax
typedef struct {
USN_RECORD_COMMON_HEADER Header;
FILE_ID_128 FileReferenceNumber;
FILE_ID_128 ParentFileReferenceNumber;
USN Usn;
DWORD Reason;
DWORD SourceInfo;
DWORD RemainingExtents;
WORD NumberOfExtents;
WORD ExtentSize;
USN_RECORD_EXTENT Extents[1];
} USN_RECORD_V4, *PUSN_RECORD_V4;
Members
Header
A USN_RECORD_COMMON_HEADER structure that describes the record length, major version, and minor version for the record.
FileReferenceNumber
The 128-bit ordinal number of the file or directory for which this record notes changes.
This value is an arbitrarily assigned value that associates a journal record with a file.
ParentFileReferenceNumber
The 128-bit ordinal number of the directory where the file or directory that is associated with this record is located.
This value is an arbitrarily assigned value that associates a journal record with a parent directory.
Usn
The USN of this record.
Reason
The flags that identify reasons for changes that have accumulated in this file or directory journal record since the file or directory opened.
When a file or directory closes, then a final USN record is generated with the USN_REASON_CLOSE flag set. The next change (for example, after the next open operation or deletion) starts a new record with a new set of reason flags.
A rename or move operation generates two USN records, one that records the old parent directory for the item, and one that records a new parent.
The following table identifies the possible flags.
SourceInfo
Additional information about the source of the change, set by the FSCTL_MARK_HANDLE of the DeviceIoControl operation.
When a thread writes a new USN record, the source information flags in the prior record continue to be present only if the thread also sets those flags. Therefore, the source information structure allows applications to filter out USN records that are set only by a known source, for example, an antivirus filter.
One of the following values can be set.
RemainingExtents
The number of extents that remain after the current USN_RECORD_V4 record. Multiple version 4.0 records may be required to describe all of the modified extents for a given file. When the RemainingExtents member is 0, the current USN_RECORD_V4 record is the last USN_RECORD_V4 record for the file. The last USN_RECORD_V4 entry for a given file is always followed by a USN_RECORD_V3 record with at least the USN_REASON_CLOSE flag set.
NumberOfExtents
The number of extents in current USN_RECORD_V4 entry.
ExtentSize
The size of each USN_RECORD_EXTENT structure in the Extents member, in bytes.
Extents[1]
An array of USN_RECORD_EXTENT structures that represent the extents in the USN_RECORD_V4 entry.
Remarks
A USN_RECORD_V4 record is only output when range tracking is turned on and the file size is equal or larger than the value of the RangeTrackFileSizeThreshold member. The user always receives one or more USN_RECORD_V4 records followed by one USN_RECORD_V3 record.
To provide a path forward compatibility in change journal clients, Microsoft provides a major and minor version number of the change journal software in the USN_RECORD_V4 structure. Your code should examine these values, examine its own compatibility with the change journal software, and gracefully handle any incompatibility if necessary.
A change in the minor version number indicates that the existing USN_RECORD_V4 structure members are still valid, but that new members may have been added between the penultimate member and the last, which is a variable-length string.
To handle such a change gracefully, your code should not do any compile-time pointer arithmetic that relies on the location of the last member. For example, a change in the minor version number makes the sizeof(USN_RECORD) call unreliable. Instead, rely on run-time calculations that use the RecordLength member.
An increase in the major version number of the change journal software indicates that the USN_RECORD_V4 structure may have undergone major changes, and that the current definition may not be reliable. If your code detects a change in the major version number of the change journal software, the code should not work with the change journal.
For more information, see Creating, Modifying, and Deleting a Change Journal.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8.1 [desktop apps only] |
| Minimum supported server | Windows Server 2012 R2 [desktop apps only] |
| Header | winioctl.h (include Windows.h) |