| Platform SDK: Hardware |
The USN_RECORD structure contains the information for a change journal version 2.0 record. Win32-based applications should not attempt to work with change journal versions earlier than 2.0.
typedef struct {
DWORD RecordLength;
WORD MajorVersion;
WORD MinorVersion;
DWORDLONG FileReferenceNumber;
DWORDLONG ParentFileReferenceNumber;
USN Usn;
LARGE_INTEGER TimeStamp;
DWORD Reason;
DWORD SourceInfo;
DWORD SecurityId;
DWORD FileAttributes;
WORD FileNameLength;
WORD FileNameOffset;
WCHAR FileName[1];
} USN_RECORD, *PUSN_RECORD;
The size in bytes of any change journal record is at most the size of the USN_RECORD 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 function GetVolumeInformation. In C, you can determine a record's size as follows:
(MaximumComponentLength * sizeof(WCHAR) + sizeof(USN_RECORD) - sizeof(WCHAR))
To maintain compatibility across version changes of the change journal software, use a run-time calculation to determine the size of the USN_RECORD structure. For more information about compatibility across version changes, see the Remarks section later in this topic.
Note that a rename or move operation generates two USN records, one recording the old parent directory for the item and one recording a new parent.
The list of valid flags is as follows. Unused bits are reserved.
| Value | Meaning |
|---|---|
| USN_REASON_BASIC_INFO_CHANGE | A user has either changed one or more file or directory attributes (such as the read-only, hidden, system, archive, or sparse attribute), or one or more time stamps. |
| USN_REASON_CLOSE | The file or directory was closed. |
| USN_REASON_COMPRESSION_CHANGE | The compression state of the file or directory was changed from or to compressed. |
| USN_REASON_DATA_EXTEND | The file or directory was added to. |
| USN_REASON_DATA_OVERWRITE | Data in the file or directory was overwritten. |
| USN_REASON_DATA_TRUNCATION | The file or directory was truncated. |
| USN_REASON_EA_CHANGE | The user made a change to the file's or directory's extended attributes. These NTFS attributes are not accessible to Win32-based applications. |
| USN_REASON_ENCRYPTION_CHANGE | The file or directory was encrypted or decrypted. |
| USN_REASON_FILE_CREATE | The file or directory was created for the first time. |
| USN_REASON_FILE_DELETE | The file or directory was deleted. |
| USN_REASON_HARD_LINK_CHANGE | An NTFS hard link was added to or removed from the file or directory. An NTFS hard link, similar to a POSIX hard link, is one of several directory entries that refer to the same file or directory. |
| USN_REASON_INDEXABLE_CHANGE | A user changed the FILE_ATTRIBUTE_NOT_CONTENT_INDEXED attribute. That is, the user changed the file or directory from one that can be content indexed to one that cannot, or vice versa. (Content indexing permits rapid searching of data by building a database of selected content.) |
| USN_REASON_NAMED_DATA_EXTEND | One or more named data streams for the file were added to. |
| USN_REASON_NAMED_DATA_OVERWRITE | Data in one or more named data streams for the file was overwritten. |
| USN_REASON_NAMED_DATA_TRUNCATION | One or more named data streams for the file was truncated. |
| USN_REASON_OBJECT_ID_CHANGE | The object identifier of the file or directory was changed. |
| USN_REASON_RENAME_NEW_NAME | The file or directory was renamed, and the file name in this USN_RECORD structure is the new name. |
| USN_REASON_RENAME_OLD_NAME | The file or directory was renamed, and the file name in this USN_RECORD structure is the previous name. |
| USN_REASON_REPARSE_POINT_CHANGE | The reparse point contained in the file or directory was changed, or a reparse point was added to or deleted from the file or directory. |
| USN_REASON_SECURITY_CHANGE | A change was made in the access rights to the file or directory. |
| USN_REASON_STREAM_CHANGE | A named stream has been added to or removed from the file, or a named stream has been renamed. |
| Value | Meaning |
|---|---|
| USN_SOURCE_DATA_MANAGEMENT | The operation provides information about a change to the file or directory made by the operating system.
A typical use is when the Remote Storage system moves data from external to local storage. Remote Storage is the hierarchical storage management software in Windows 2000. Such a move usually at a minimum adds the USN_REASON_DATA_OVERWRITE flag to a USN record. However, the data has not changed from the users' point of view. By noting USN_SOURCE_DATA_MANAGEMENT in the SourceInfo member, you can determine that although a write operation was performed on the item, data has not changed. |
| USN_SOURCE_AUXILIARY_DATA | The operation adds a private data stream to a file or directory.
An example might be a virus detector adding checksum information. As the virus detector modifies the item, the system generates USN records. USN_SOURCE_AUXILIARY_DATA indicates that the modifications did not change the application data. |
When working with FileName, do not count on the file name containing a trailing '\0' delimiter, but instead determine the length of the file name with FileNameLength.
Do not perform any compile-time pointer arithmetic using FileName. Instead, make any necessary calculations at run time using the value of the FileNameOffset member. Doing so helps make your code compatible with any future versions of USN_RECORD.
In output buffers returned from DeviceIoControl operations that work with USN_RECORD, all records are aligned on 64-bit boundaries from the start of the buffer.
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 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 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. In order 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 using the RecordLength member.
An increase in the major version number of the change journal software indicates that the USN_RECORD 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 on working with change journal records, see Creating, Modifying, and Deleting a Change Journal.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Winioctl.h.
Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, GetVolumeInformation, FSCTL_MARK_HANDLE, FSCTL_READ_USN_JOURNAL, GetFileAttributes, READ_USN_JOURNAL_DATA