| Platform SDK: Hardware |
The READ_USN_JOURNAL_DATA structure contains information defining a set of change journal records to return to the calling process. The FSCTL_READ_USN_JOURNAL operation for the DeviceIoControl function uses READ_USN_JOURNAL_DATA.
typedef struct {
USN StartUsn;
DWORD ReasonMask;
DWORD ReturnOnlyOnClose;
DWORDLONG Timeout;
DWORDLONG BytesToWaitFor;
DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA, *PREAD_USN_JOURNAL_DATA;
To start the read operation at the first record in the journal, set the StartUsn member to zero. Because a USN is contained in every journal record, the output buffer tells at which record the read operation actually started.
To start the read operation at a specific record, set StartUsn to that record's USN.
If a nonzero USN is specified that is less than the first USN in the change journal, then an error occurs and the ERROR_JOURNAL_ENTRY_DELETED error code is returned. This code may indicate a case in which the specified USN was valid at one time but has since been deleted.
For more information on navigating the change journal buffer returned in READ_USN_JOURNAL_DATA, see Walking a Buffer of Change Journal Records.
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 were 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 the USN_RECORD structure holding this journal record is the new name. |
| USN_REASON_RENAME_OLD_NAME | The file or directory was renamed, and the file name in the USN_RECORD structure holding this journal record 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 permissions to the file or directory. |
| USN_REASON_STREAM_CHANGE | A named stream has been added to or removed from the file or directory, or a named stream has been renamed. |
To receive notification when the final handle for the changed file or directory is closed, rather than at the time a change occurs, set ReturnOnlyOnClose to any nonzero value and specify the USN_REASON_CLOSE flag in the ReasonMask member.
All changes indicated by ReasonMask flags eventually generate a call to the change journal software when the file is closed. If your DeviceIoControl call is waiting for the file to be closed, that call in turn will allow your DeviceIoControl call to return. In the event that a file or directory is not closed prior to a volume failure, operating system failure, or shutdown, a cleanup call to the change journal software occurs the next time the volume is mounted. The call occurs even if there is an intervening system restart.
To receive notification the first time each change is logged, as well as at cleanup, set ReturnOnlyOnClose to zero.
Whether ReturnOnlyOnClose is zero or nonzero, the records generated at cleanup log within the change journal all reasons for USN changes that occurred to the file or directory. Each time a final close operation occurs for an item, a USN close record is written to the change journal, and the ReasonMask flags for the item are all reset.
For a file or directory for which no user data exists (for example, a volume mount point), the final close operation occurs when the CloseHandle function is called on the last user handle to the item.
If Timeout is zero, BytesToWaitFor is nonzero, and the FSCTL_READ_USN_JOURNAL operation call reaches the end of the change journal without finding data to return, FSCTL_READ_USN_JOURNAL waits until BytesToWaitFor bytes of unfiltered data have been added to the change journal and then returns the specified records.
If Timeout is nonzero, BytesToWaitFor is nonzero, and the FSCTL_READ_USN_JOURNAL operation call reaches the end of the change journal without finding data to return, FSCTL_READ_USN_JOURNAL waits Timeout seconds and then attempts to return the specified records. After Timeout seconds, FSCTL_READ_USN_JOURNAL returns any records available within the specified range.
In either case, after the time-out period any new data appended to the change journal is processed. If there are still no records to return from the specified set, the time-out period is repeated. In this mode, FSCTL_READ_USN_JOURNAL remains outstanding until at least one record is returned or I/O is canceled.
If BytesToWaitFor is zero, then Timeout is ignored. Timeout is also ignored for asynchronously opened handles.
If BytesToWaitFor is zero, then Timeout is ignored. In this case, the FSCTL_READ_USN_JOURNAL operation always returns with success when the end of the change journal file is encountered. It also returns with the USN that should be used for the next FSCTL_READ_USN_JOURNAL operation. When the returned next USN is the same as the StartUsn supplied, there are no records available. The calling process should not use FSCTL_READ_USN_JOURNAL again immediately.
Because the amount of data returned cannot be predicted when BytesToWaitFor is zero, you run a risk of overflowing the output buffer. To reduce this risk, specify a nonzero BytesToWaitFor value in repeated FSCTL_READ_USN_JOURNAL operations until all records in the change journal are exhausted. Then specify zero to await new records.
Alternatively, use the lpBytesReturned parameter of DeviceIoControl in the FSCTL_READ_USN_JOURNAL operation call to determine the amount of data available, reallocate the output buffer (with room to spare for new records), and call DeviceIoControl again.
NTFS can miss putting events in the change journal if the change journal is stopped and restarted or deleted and recreated. If either of these events occurs, NTFS gives the journal a new identifier. If the journal identifier you supply in the UsnJournalID member does not agree with the current journal identifier, the call to DeviceIoControl fails and returns an appropriate error code. To obtain the new journal identifier, call DeviceIoControl with the FSCTL_QUERY_USN_JOURNAL operation.
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, CloseHandle, DeviceIoControl, FSCTL_QUERY_USN_JOURNAL, FSCTL_READ_USN_JOURNAL, USN_RECORD