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) );
|
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 |
|---|---|
|
The structure is a USN_RECORD_V2 structure and the remainder of the structure should be parsed using that layout. |
|
The structure is a USN_RECORD_V3 structure and the remainder of the structure should be parsed using that layout. |
|
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) |