USN_RECORD_V3-Struktur (winioctl.h)

Enthält die Informationen für einen Änderungsjournaldatensatz der Version 3.0 der Updatesequenznummer (USN). Der Datensatz der Version 2.0 wird durch die USN_RECORD_V2-Struktur (auch als USN_RECORD-Struktur bezeichnet) definiert.

Syntax

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  FILE_ID_128   FileReferenceNumber;
  FILE_ID_128   ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V3, *PUSN_RECORD_V3;

Member

RecordLength

Die Gesamtlänge eines Datensatzes in Bytes.

Da USN_RECORD_V3 eine Variable ist, sollte der RecordLength-Member verwendet werden, wenn die Adresse des nächsten Datensatzes in einem Ausgabepuffer berechnet wird, z. B. ein Puffer, der von Vorgängen für die DeviceIoControl-Funktion zurückgegeben wird, die mit USN_RECORD_V3 arbeiten.

Die Größe eines Änderungsjournaldatensatzes in Byte entspricht höchstens der Größe der USN_RECORD_V3-Struktur , plus MaximumComponentLength-Zeichen minus 1 (für das in der Struktur deklarierte Zeichen) mal die Größe eines Breitzeichens. Der Wert von MaximumComponentLength kann durch Aufrufen der
GetVolumeInformation-Funktion . In C können Sie eine Datensatzgröße mithilfe des folgenden Codebeispiels ermitteln.

C++
  MaximumChangeJournalRecordSize = 
      QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR) 
       + sizeof(USN_RECORD_V3) );
Um die Kompatibilität zwischen Versionsänderungen der Änderungsjournalsoftware zu gewährleisten, verwenden Sie eine Laufzeitberechnung, um die Größe der USN_RECORD_V3-Struktur zu bestimmen. Weitere Informationen zur Kompatibilität zwischen Versionsänderungen finden Sie im Abschnitt Hinweise in diesem Thema.

MajorVersion

Die Hauptversionsnummer der Änderungsjournalsoftware für diesen Datensatz.

Wenn die Änderungsjournalsoftware beispielsweise Version 3.0 ist, lautet die Hauptversionsnummer 3.

Wert Bedeutung
2
Die -Struktur ist eine USN_RECORD_V2-Struktur , und der Rest der -Struktur sollte mit diesem Layout analysiert werden.
3
Die -Struktur ist eine USN_RECORD_V3-Struktur , und der Rest der Struktur sollte mithilfe dieses Layouts analysiert werden.
4
Die Struktur ist eine [USN_RECORD_V4-Struktur](ns-winioctl-usn_record_v4.md), und der Rest der Struktur sollte mit diesem Layout analysiert werden.

MinorVersion

Die Nebenversionsnummer der Änderungsjournalsoftware für diesen Datensatz. Wenn die Änderungsjournalsoftware z. B. Version 3.0 ist, ist die Nebenversionsnummer null.

FileReferenceNumber

Die 128-Bit-Ordnungszahl der Datei oder des Verzeichnisses, für die sich dieser Datensatz ändert.

Dies ist ein willkürlich zugewiesener Wert, der einem Journaldatensatz einer Datei zuordnet.

ParentFileReferenceNumber

Die 128-Bit-Ordnungszahl des Verzeichnisses, in dem sich die Diesem Datensatz zugeordnete Datei oder das Verzeichnis befindet.

Dies ist ein willkürlich zugewiesener Wert, der einen Journaldatensatz einem übergeordneten Verzeichnis zuordnet.

Usn

Der USN dieses Datensatzes.

TimeStamp

Der UTC-Standardzeitstempel (FILETIME) dieses Datensatzes im 64-Bit-Format.

Reason

Die Flags, die Gründe für Änderungen identifizieren, die sich seit dem Öffnen der Datei oder des Verzeichnisses in diesem Datei- oder Verzeichnisjournaldatensatz angesammelt haben.

Wenn eine Datei oder ein Verzeichnis geschlossen wird, wird ein endgültiger USN-Eintrag mit festgelegtem USN_REASON_CLOSE-Flag generiert. Die nächste Änderung (z. B. nach dem nächsten geöffneten Vorgang oder Löschvorgang) startet einen neuen Datensatz mit einem neuen Satz von Ursachenflags.

Bei einem Umbenennungs- oder Verschiebungsvorgang werden zwei USN-Einträge generiert: einer, der das alte übergeordnete Verzeichnis für das Element aufzeichnet, und einer, der ein neues übergeordnetes Verzeichnis aufzeichnet.

In der folgenden Tabelle sind die möglichen Flags aufgeführt.

Hinweis Nicht verwendete Bits sind reserviert.
 
Wert Bedeutung
USN_REASON_BASIC_INFO_CHANGE
0x00008000
Ein Benutzer hat entweder ein oder mehrere Datei- oder Verzeichnisattribute (z. B. das schreibgeschützte, ausgeblendete, System-, Archiv- oder Sparse-Attribut) oder einen oder mehrere Zeitstempel geändert.
USN_REASON_CLOSE
0x80000000
Die Datei oder das Verzeichnis ist geschlossen.
USN_REASON_COMPRESSION_CHANGE
0x00020000
Der Komprimierungsstatus der Datei oder des Verzeichnisses wird von oder in komprimiert geändert.
USN_REASON_DATA_EXTEND
0x00000002
Die Datei oder das Verzeichnis wird erweitert (hinzugefügt).
USN_REASON_DATA_OVERWRITE
0x00000001
Die Daten in der Datei oder im Verzeichnis werden überschrieben.
USN_REASON_DATA_TRUNCATION
0x00000004
Die Datei oder das Verzeichnis wird abgeschnitten.
USN_REASON_EA_CHANGE
0x00000400
Der Benutzer hat eine Änderung an den erweiterten Attributen einer Datei oder eines Verzeichnisses vorgenommen.
USN_REASON_ENCRYPTION_CHANGE
0x00040000
Die Datei oder das Verzeichnis wird verschlüsselt oder entschlüsselt.
USN_REASON_FILE_CREATE
0x00000100
Die Datei oder das Verzeichnis wird zum ersten Mal erstellt.
USN_REASON_FILE_DELETE
0x00000200
Die Datei oder das Verzeichnis wird gelöscht.
USN_REASON_HARD_LINK_CHANGE
0x00010000
Eine feste Verknüpfung des NTFS-Dateisystems wird der Datei oder dem Verzeichnis hinzugefügt oder daraus entfernt.

Eine feste Verknüpfung des NTFS-Dateisystems, ähnlich wie bei einer POSIX-Hard-Verknüpfung, ist einer von mehreren Verzeichniseinträgen, die die gleiche Datei oder dasselbe Verzeichnis sehen.

USN_REASON_INDEXABLE_CHANGE
0x00004000
Ein Benutzer ändert das attribut FILE_ATTRIBUTE_NOT_CONTENT_INDEXED .

Das heißt, der Benutzer ändert die Datei oder das Verzeichnis von einem Verzeichnis, in dem Inhalte indiziert werden können, in ein Verzeichnis, in dem Inhalte nicht indiziert werden können, oder umgekehrt. Die Inhaltsindizierung ermöglicht eine schnelle Suche nach Daten, indem eine Datenbank mit ausgewählten Inhalten erstellt wird.

USN_REASON_INTEGRITY_CHANGE
0x00800000
Ein Benutzer hat den Status des FILE_ATTRIBUTE_INTEGRITY_STREAM-Attributs für den angegebenen Stream geändert.

Im ReFS-Dateisystem verwalten Integritätsdatenströme eine Prüfsumme aller Daten für diesen Datenstrom, sodass der Inhalt der Datei während Lese- oder Schreibvorgängen überprüft werden kann.

USN_REASON_NAMED_DATA_EXTEND
0x00000020
Die benannten Datenströme für eine Datei werden erweitert (hinzugefügt).
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
Die Daten in einem oder mehreren benannten Datenströmen für eine Datei werden überschrieben.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
Der benannte Datenstrom für eine Datei wird abgeschnitten.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
Der Objektbezeichner einer Datei oder eines Verzeichnisses wird geändert.
USN_REASON_RENAME_NEW_NAME
0x00002000
Eine Datei oder ein Verzeichnis wird umbenannt, und der Dateiname in der USN_RECORD_V3-Struktur ist der neue Name.
USN_REASON_RENAME_OLD_NAME
0x00001000
Die Datei oder das Verzeichnis wird umbenannt, und der Dateiname in der USN_RECORD_V3-Struktur ist der vorherige Name.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
Der Analysepunkt, der in einer Datei oder einem Verzeichnis enthalten ist, wird geändert, oder ein Analysepunkt wird einer Datei oder einem Verzeichnis hinzugefügt oder aus diesem gelöscht.
USN_REASON_SECURITY_CHANGE
0x00000800
Die Zugriffsrechte für eine Datei oder ein Verzeichnis werden geändert.
USN_REASON_STREAM_CHANGE
0x00200000
Ein benannter Stream wird einer Datei hinzugefügt oder daraus entfernt, oder ein benannter Stream wird umbenannt.
USN_REASON_TRANSACTED_CHANGE
0x00400000
Der angegebene Stream wird durch eine TxF-Transaktion geändert.

SourceInfo

Zusätzliche Informationen zur Quelle der Änderung, die vom FSCTL_MARK_HANDLE des DeviceIoControl-Vorgangs festgelegt wird.

Wenn ein Thread einen neuen USN-Datensatz schreibt, sind die Quellinformationsflags im vorherigen Datensatz nur dann weiterhin vorhanden, wenn der Thread auch diese Flags festlegt. Daher ermöglicht die Quellinformationsstruktur Anwendungen, USN-Datensätze herauszufiltern, die nur von einer bekannten Quelle festgelegt werden, z. B. einem Antivirenfilter.

Einer der beiden folgenden Werte kann festgelegt werden.

Wert Bedeutung
USN_SOURCE_AUXILIARY_DATA
0x00000002
Der Vorgang fügt einer Datei oder einem Verzeichnis einen privaten Datenstrom hinzu.

Ein Beispiel könnte ein Virusdetektor sein, der Prüfsummeninformationen hinzufügt. Wenn der Virusdetektor das Element ändert, generiert das System USN-Datensätze. USN_SOURCE_AUXILIARY_DATA gibt an, dass die Änderungen die Anwendungsdaten nicht geändert haben.

USN_SOURCE_DATA_MANAGEMENT
0x00000001
Der Vorgang stellt Informationen zu einer Änderung der Datei oder des Verzeichnisses bereit, die vom Betriebssystem vorgenommen wurde.

Ein typischer Einsatz ist, wenn das Remotespeichersystem Daten von externem in den lokalen Speicher verschiebt. Remotespeicher ist die hierarchische Speicherverwaltungssoftware. Eine solche Verschiebung fügt in der Regel mindestens das USN_REASON_DATA_OVERWRITE-Flag einem USN-Datensatz hinzu. Die Daten haben sich jedoch aus Sicht des Benutzers nicht geändert. Wenn Sie USN_SOURCE_DATA_MANAGEMENT im SourceInfo-Member notieren, können Sie feststellen, dass die Daten nicht geändert wurden, obwohl ein Schreibvorgang für das Element ausgeführt wird.

USN_SOURCE_REPLICATION_MANAGEMENT
0x00000004
Der Vorgang ändert eine Datei so, dass sie dem Inhalt derselben Datei entspricht, die in einem anderen Element des Replikatsatzes vorhanden ist.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT
0x00000008
Der Vorgang ändert eine Datei auf Clientsystemen so, dass sie dem Inhalt derselben Datei entspricht, die in der Cloud vorhanden ist.

SecurityId

Der eindeutige Sicherheitsbezeichner, der der Datei oder dem Verzeichnis zugewiesen ist, die diesem Datensatz zugeordnet sind.

FileAttributes

Die Attribute für die Datei oder das Verzeichnis, die diesem Datensatz zugeordnet sind, wie sie von der GetFileAttributes-Funktion zurückgegeben werden. Attribute von Streams, die der Datei oder dem Verzeichnis zugeordnet sind, werden ausgeschlossen.

FileNameLength

Die Länge des Namens der Datei oder des Verzeichnisses, die diesem Datensatz zugeordnet ist, in Bytes. Das FileName-Element enthält diesen Namen. Verwenden Sie dieses Element, um die Länge des Dateinamens zu bestimmen, anstatt von einem nachfolgenden "\0" abhängig zu sein, um den Dateinamen in FileName zu trennen.

FileNameOffset

Der Offset des FileName-Elements vom Anfang der Struktur.

FileName[1]

Der Name der Datei oder des Verzeichnisses, die diesem Datensatz im Unicode-Format zugeordnet ist. Dieser Datei- oder Verzeichnisname hat eine variable Länge.

Zählen Sie beim Arbeiten mit FileName nicht auf den Dateinamen, der ein nachfolgendes Trennzeichen "\0" enthält, sondern bestimmen Sie stattdessen die Länge des Dateinamens mithilfe von FileNameLength.

Führen Sie keine Kompilierzeitzeigerarithmetik mit FileName aus. Führen Sie stattdessen die erforderlichen Berechnungen zur Laufzeit durch, indem Sie den Wert des FileNameOffset-Elements verwenden. Dadurch können Sie Ihren Code mit zukünftigen Versionen von USN_RECORD_V3 kompatibel machen.

Hinweise

In Ausgabepuffern, die von DeviceIoControl-Vorgängen zurückgegeben werden, die mit USN_RECORD_V3 funktionieren, werden alle Datensätze vom Anfang des Puffers an 64-Bit-Grenzen ausgerichtet.

Wenn die Bereichsnachverfolgung aktiviert ist, wechselt NTFS dazu, nur USN_RECORD_V3 Datensätze als Ausgabe zu erzeugen.

Um einen Pfad für die Aufwärtskompatibilität in Änderungsjournalclients bereitzustellen, stellt Microsoft eine Haupt- und Nebenversionsnummer der Änderungsjournalsoftware in der USN_RECORD_V3-Struktur bereit. Ihr Code sollte diese Werte untersuchen, seine eigene Kompatibilität mit der Änderungsjournalsoftware ermitteln und bei Bedarf alle Inkompatibilitäten ordnungsgemäß behandeln.

Eine Änderung der Nebenversionsnummer gibt an, dass die vorhandenen USN_RECORD_V3-Strukturmember weiterhin gültig sind, dass jedoch möglicherweise neue Member zwischen dem vorletzten und dem letzten Element hinzugefügt wurden, was eine Zeichenfolge mit variabler Länge ist.

Um eine solche Änderung ordnungsgemäß zu behandeln, sollte Ihr Code keine Kompilierzeitzeigerarithmetik ausführen, die von der Position des letzten Elements abhängig ist. Dies macht z. B. den C-Code sizeof(USN_RECORD) unzuverlässig. Verlassen Sie sich stattdessen auf Laufzeitberechnungen, indem Sie das RecordLength-Element verwenden.

Eine Erhöhung der Hauptversionsnummer der Änderungsjournalsoftware weist darauf hin, dass die USN_RECORD_V3 Struktur möglicherweise erhebliche Änderungen erfahren hat und dass die aktuelle Definition möglicherweise nicht zuverlässig ist. Wenn Ihr Code eine Änderung der Hauptversionsnummer der Änderungsjournalsoftware erkennt, sollte dies nicht mit dem Änderungsjournal funktionieren.

Weitere Informationen finden Sie unter Erstellen, Ändern und Löschen einer Änderung Journal.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2012 [nur Desktop-Apps]
Kopfzeile winioctl.h (einschließlich Windows.h)

Weitere Informationen

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V2

USN_RECORD_V4 Struktur

Volumeverwaltungsstrukturen