USN_RECORD_COMMON_HEADER structure (winioctl.h)

Contains the information for an update sequence number (USN) change journal version 3.0 record. The version 2.0 record is defined by the USN_RECORD_V2 structure (also called USN_RECORD structure).

Syntax

typedef struct {
  DWORD RecordLength;
  WORD  MajorVersion;
  WORD  MinorVersion;
} USN_RECORD_COMMON_HEADER, *PUSN_RECORD_COMMON_HEADER;

Members

RecordLength

The total length of a record, in bytes.

Because USN_RECORD_V3 is a variable size, the RecordLength member should be used when calculating the address of the next record in an output buffer, for example, a buffer that is returned from operations for the DeviceIoControl function that work with USN_RECORD_V3.

The size in bytes of any change journal record is at most the size of the USN_RECORD_V3 structure, plus MaximumComponentLength characters minus 1 (for the character declared in the structure) times the size of a wide character. The value of MaximumComponentLength may be determined by calling the
GetVolumeInformation function. In C, you can determine a record size by using the following code example.

C++
  MaximumChangeJournalRecordSize = 
      QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR) 
       + sizeof(USN_RECORD_V3) );
To maintain compatibility across version changes of the change journal software, use a run-time calculation to determine the size of the USN_RECORD_V3 structure. For more information about compatibility across version changes, see the Remarks section in this topic.

MajorVersion

The major version number of the change journal software for this record.

For example, if the change journal software is version 3.0, the major version number is 3.

Value Meaning
2
The structure is a USN_RECORD_V2 structure and the remainder of the structure should be parsed using that layout.
3
The structure is a USN_RECORD_V3 structure and the remainder of the structure should be parsed using that layout.
4
The structure is a USN_RECORD_V4 structure and the remainder of the structure should be parsed using that layout.

MinorVersion

The minor version number of the change journal software for this record. For example, if the change journal software is version 3.0, the minor version number is zero.

Remarks

In output buffers returned from DeviceIoControl operations that work with USN_RECORD_V3, all records are aligned on 64-bit boundaries from the start of the buffer.

When range tracking is turned on, NTFS switches to producing only USN_RECORD_V3 records as output.

To provide a path for upward compatibility in change journal clients, Microsoft provides a major and minor version number of the change journal software in the USN_RECORD_V3 structure. Your code should examine these values, detect its own compatibility with the change journal software, and if necessary gracefully handle any incompatibility.

A change in the minor version number indicates that the existing USN_RECORD_V3 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, this makes the C code sizeof(USN_RECORD) unreliable. Instead, rely on run-time calculations by using the RecordLength member.

An increase in the major version number of the change journal software indicates that the USN_RECORD_V3 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, it should not work with the change journal.

For more information, see Creating, Modifying, and Deleting a Change Journal.

Requirements

   
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Header winioctl.h (include Windows.h)

See also

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V2

USN_RECORD_V4

Volume Management Structures