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) );
|
MajorVersion
Die Hauptversionsnummer der Änderungsjournalsoftware für diesen Datensatz.
Wenn die Änderungsjournalsoftware beispielsweise Version 3.0 ist, lautet die Hauptversionsnummer 3.
| Wert | Bedeutung |
|---|---|
|
Die -Struktur ist eine USN_RECORD_V2-Struktur , und der Rest der -Struktur sollte mit diesem Layout analysiert werden. |
|
Die -Struktur ist eine USN_RECORD_V3-Struktur , und der Rest der Struktur sollte mithilfe dieses Layouts analysiert werden. |
|
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.
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.
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) |