ChangeJournal Class

Namespace: Meziantou.Framework.Win32
Assembly: Meziantou.Framework.Win32.ChangeJournal.dll
Package: Meziantou.Framework.Win32.ChangeJournal 5.0.6
Source: ChangeJournal.cs
Available in package assets: net10.0net11.0

Supported on windows5.1.2600

Provides access to the NTFS change journal (Update Sequence Number journal) for a volume. The change journal records information about file and directory changes on an NTFS volume.

[SupportedOSPlatform("windows5.1.2600")]
public sealed class ChangeJournal : IDisposable

Implements

IDisposable

Properties

Name	Description
Data	Gets the current metadata about the change journal.
Entries	Gets a collection of all change journal entries.

Data

ChangeJournal.cs

Gets the current metadata about the change journal.

public JournalData Data { get; }

Property value

JournalData

Entries

ChangeJournal.cs

Gets a collection of all change journal entries.

public IEnumerable<ChangeJournalEntry> Entries { get; }

Property value

IEnumerable<ChangeJournalEntry>

Methods

Name	Description
Create(long, long)	Creates a new change journal or modifies an existing one.
Create(ulong, ulong)	Creates a new change journal or modifies an existing one.
Delete()	Deletes the change journal and waits for the deletion to complete.
Delete(bool)	Deletes the change journal.
Dispose()	Releases all resources used by the current instance of the `ChangeJournal` class.
EnableTrackModifiedRanges(ulong, long)	Enables range tracking for the change journal.
GetEntries(ChangeReason, bool, TimeSpan)	Gets change journal entries with the specified filter criteria.
GetEntries(Usn, ChangeReason, bool, TimeSpan)	Gets change journal entries starting from a specific USN with the specified filter criteria.
GetEntry(SafeFileHandle)	Gets the change journal entry for a specific file or directory by handle.
GetEntry(string)	Gets the change journal entry for a specific file or directory by path.
Open(DriveInfo)	Opens the change journal for the specified drive.
Open(DriveInfo, bool)	Opens the change journal for the specified drive.
RefreshJournalData()	Refreshes the journal metadata by reading the current state from the change journal.

Create overloads

Create(long, long)

ChangeJournal.cs

Creates a new change journal or modifies an existing one.

public void Create(long maximumSize, long allocationDelta)

Parameters

maximumSize long: The maximum size, in bytes, that the journal can use on the volume.
allocationDelta long: The size, in bytes, by which the journal grows when needed.

Exceptions

ArgumentOutOfRangeException: Thrown when maximumSize or allocationDelta is negative.

Create(ulong, ulong)

ChangeJournal.cs

Creates a new change journal or modifies an existing one.

public void Create(ulong maximumSize, ulong allocationDelta)

Parameters

maximumSize ulong: The maximum size, in bytes, that the journal can use on the volume.
allocationDelta ulong: The size, in bytes, by which the journal grows when needed.

Delete overloads

Delete()

ChangeJournal.cs

Deletes the change journal and waits for the deletion to complete.

public void Delete()

Exceptions

Win32Exception: Thrown when the operation fails.

Remarks

Deleting a change journal requires a scan of every file on the volume, so it can take a long time and continues across system restarts.

Delete(bool)

ChangeJournal.cs

Deletes the change journal.

public void Delete(bool waitForCompletion)

Parameters

waitForCompletion bool: If true, waits for the deletion to complete; otherwise, starts the deletion and returns immediately.

Exceptions

Win32Exception: Thrown when the operation fails.

Remarks

Deleting a change journal requires a scan of every file on the volume, so it can take a long time and continues across system restarts. While the deletion is in progress, any attempt to create, modify, delete, or query the change journal fails with ERROR_JOURNAL_DELETE_IN_PROGRESS.

Dispose()

ChangeJournal.cs

Releases all resources used by the current instance of the ChangeJournal class.

public void Dispose()

EnableTrackModifiedRanges(ulong, long)

ChangeJournal.cs

Enables range tracking for the change journal.

public void EnableTrackModifiedRanges(ulong chunkSize, long fileSizeThreshold)

Parameters

chunkSize ulong: The granularity of tracked ranges.
fileSizeThreshold long: The file size threshold to start tracking ranges for files with equal or larger size.

Remarks

Range tracking is reflected by JournalData.Flags, JournalData.RangeTrackChunkSize and JournalData.RangeTrackFileSizeThreshold on ChangeJournal.Data.

GetEntries overloads

GetEntries(ChangeReason, bool, TimeSpan)

ChangeJournal.cs

Gets change journal entries with the specified filter criteria.

public IEnumerable<ChangeJournalEntry> GetEntries(ChangeReason reasonFilter, bool returnOnlyOnClose, TimeSpan timeout)

Parameters

reasonFilter ChangeReason: A filter that specifies which types of changes to include.
returnOnlyOnClose bool: If true, returns only entries with the Close reason flag set.
timeout TimeSpan: The time to wait for new entries once the end of the journal is reached. Use TimeSpan.Zero to stop there instead of waiting.

Returns

IEnumerable<ChangeJournalEntry> A collection of change journal entries matching the filter criteria.

Remarks

A non-zero timeout makes the enumeration wait for a matching entry rather than end, so it never completes on its own. The wait happens inside a synchronous call to the driver and cannot be cancelled, which means a thread enumerating with a non-zero timeout stays blocked until an entry matches the filter.

GetEntries(Usn, ChangeReason, bool, TimeSpan)

ChangeJournal.cs

Gets change journal entries starting from a specific USN with the specified filter criteria.

public IEnumerable<ChangeJournalEntry> GetEntries(Usn currentUSN, ChangeReason reasonFilter, bool returnOnlyOnClose, TimeSpan timeout)

Parameters

currentUSN Usn: The USN to start reading from.
reasonFilter ChangeReason: A filter that specifies which types of changes to include.
returnOnlyOnClose bool: If true, returns only entries with the Close reason flag set.
timeout TimeSpan: The time to wait for new entries once the end of the journal is reached. Use TimeSpan.Zero to stop there instead of waiting.

Returns

IEnumerable<ChangeJournalEntry> A collection of change journal entries matching the filter criteria.

Exceptions

ArgumentOutOfRangeException: Thrown when currentUSN is outside the valid range.

Remarks

GetEntry overloads

GetEntry(SafeFileHandle)

ChangeJournal.cs

Gets the change journal entry for a specific file or directory by handle.

public static ChangeJournalEntryVersion2or3 GetEntry(SafeFileHandle handle)

Parameters

handle SafeFileHandle: A handle to the file or directory.

Returns

ChangeJournalEntryVersion2or3 The change journal entry for the specified file or directory.

Exceptions

Win32Exception: Thrown when the operation fails.

GetEntry(string)

ChangeJournal.cs

Gets the change journal entry for a specific file or directory by path.

public static ChangeJournalEntryVersion2or3 GetEntry(string path)

Parameters

path string: The path to the file or directory.

Returns

ChangeJournalEntryVersion2or3 The change journal entry for the specified file or directory.

Exceptions

ArgumentNullException: Thrown when path is null.
Win32Exception: Thrown when the operation fails.

Open overloads

Open(DriveInfo)

ChangeJournal.cs

Opens the change journal for the specified drive.

public static ChangeJournal Open(DriveInfo driveInfo)

Parameters

driveInfo DriveInfo: The drive to open the change journal for.

Returns

ChangeJournal A ChangeJournal instance for accessing the change journal.

Exceptions

ArgumentNullException: Thrown when driveInfo is null.
Win32Exception: Thrown when the operation fails.

Open(DriveInfo, bool)

ChangeJournal.cs

Opens the change journal for the specified drive.

public static ChangeJournal Open(DriveInfo driveInfo, bool unprivileged)

Parameters

driveInfo DriveInfo: The drive to open the change journal for.
unprivileged bool: If true, uses unprivileged access mode; otherwise, uses standard access mode.

Returns

ChangeJournal A ChangeJournal instance for accessing the change journal.

Exceptions

ArgumentNullException: Thrown when driveInfo is null.
Win32Exception: Thrown when the operation fails.

RefreshJournalData()

ChangeJournal.cs

Refreshes the journal metadata by reading the current state from the change journal.

public void RefreshJournalData()