Freigeben über


READ_USN_JOURNAL_DATA_V0-Struktur (winioctl.h)

Enthält Informationen, die einen Satz von USN-Änderungsjournaldatensätzen (Update Sequence Number) definieren, um zum aufrufenden Prozess zurückzukehren. Sie wird von den FSCTL_QUERY_USN_JOURNAL- und FSCTL_READ_USN_JOURNAL-Steuerungscodes verwendet. Vor Windows 8 und Windows Server 2012 wurde diese Struktur READ_USN_JOURNAL_DATA genannt. Verwenden Sie diesen Namen, um mit älteren SDKs und Compilern zu kompilieren. Windows Server 2012 wurde READ_USN_JOURNAL_DATA_V1 zur Unterstützung von 128-Bit-Dateibezeichnern eingeführt, die von ReFS verwendet werden.

Syntax

typedef struct {
  USN       StartUsn;
  DWORD     ReasonMask;
  DWORD     ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;

Member

StartUsn

Der USN, an dem mit dem Lesen des Änderungsjournals begonnen werden soll.

Um den Lesevorgang am ersten Datensatz im Journal zu starten, legen Sie den StartUsn-Member auf 0 (null) fest. Da in jedem Journaldatensatz ein USN enthalten ist, teilt der Ausgabepuffer mit, an welchem Datensatz der Lesevorgang tatsächlich gestartet wurde.

Um den Lesevorgang an einem bestimmten Datensatz zu starten, legen Sie StartUsn auf diesen Datensatz USN fest.

Wenn ein USN ungleich null angegeben wird, der kleiner als der erste USN im Änderungsjournal ist, tritt ein Fehler auf, und der ERROR_JOURNAL_ENTRY_DELETED Fehlercode wird zurückgegeben. Dieser Code kann einen Fall angeben, in dem die angegebene USN gleichzeitig gültig ist, aber seitdem gelöscht wurde.

Weitere Informationen zum Navigieren im Änderungsjournalpuffer, der in READ_USN_JOURNAL_DATA_V0 zurückgegeben wird, finden Sie unter Walk a Buffer of Change Journal Records.

ReasonMask

Eine Maske von Flags, wobei jedes Flag eine Änderung anzeigt, für die die Datei oder das Verzeichnis einen Datensatz im Änderungsjournal enthält. Um in einem FSCTL_READ_USN_JOURNAL-Vorgang zurückgegeben zu werden, muss für einen Änderungsjournaldatensatz mindestens eines dieser Flags festgelegt sein.

Die Liste der gültigen Flags lautet wie folgt. 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 hinzugefügt.
USN_REASON_DATA_OVERWRITE
0x00000001
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 nimmt eine Änderung an den erweiterten Datei- oder Verzeichnisattributen vor. Auf diese NTFS-Dateisystemattribute kann nicht für Windows-basierte Anwendungen zugegriffen werden.
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 hat das attribut FILE_ATTRIBUTE_NOT_CONTENT_INDEXED geändert. Das heißt, der Benutzer hat die Datei oder das Verzeichnis von einer Datei, die indiziert werden kann, in ein Verzeichnis geändert, das nicht oder umgekehrt ist. (Die Inhaltsindizierung ermöglicht eine schnelle Suche nach Daten, indem eine Datenbank mit ausgewählten Inhalten erstellt wird.)
USN_REASON_NAMED_DATA_EXTEND
0x00000020
Mindestens ein benannter Datenstrom für die Datei wurde hinzugefügt.
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
Daten in einem oder mehreren benannten Datenströmen für die Datei werden überschrieben.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
Mindestens ein benannter Datenstrom für die Datei wird abgeschnitten.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
Der Objektbezeichner der Datei oder des Verzeichnisses wird geändert.
USN_REASON_RENAME_NEW_NAME
0x00002000
Die Datei oder das Verzeichnis wird umbenannt, und der Dateiname in der USN_RECORD_V2 - oder USN_RECORD_V3-Struktur , die diesen Journaldatensatz enthält, ist der neue Name.
USN_REASON_RENAME_OLD_NAME
0x00001000
Die Datei oder das Verzeichnis wird umbenannt, und der Dateiname in der USN_RECORD_V2 - oder USN_RECORD_V3-Struktur , die diesen Journaldatensatz enthält, ist der vorherige Name.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
Der analysepunkt, der in der Datei oder im Verzeichnis enthalten ist, wird geändert, oder ein Analysepunkt wird der Datei oder dem Verzeichnis hinzugefügt oder daraus gelöscht.
USN_REASON_SECURITY_CHANGE
0x00000800
An den Zugriffsberechtigungen für die Datei oder das Verzeichnis wird eine Änderung vorgenommen.
USN_REASON_STREAM_CHANGE
0x00200000
Ein benannter Stream wird der Datei oder dem Verzeichnis hinzugefügt oder daraus entfernt, oder ein benannter Stream wird umbenannt.

ReturnOnlyOnClose

Ein -Wert, der angibt, wann Änderungsjournaldatensätze zurückgegeben werden sollen.

Um eine Benachrichtigung zu erhalten, wenn das endgültige Handle für die geänderte Datei oder das geänderte Verzeichnis geschlossen wird, legen Sie ReturnOnlyOnClose auf einen beliebigen Wert ungleich null fest, und geben Sie das flag USN_REASON_CLOSE im ReasonMask-Element an.

Alle Änderungen, die durch ReasonMask-Flags angegeben werden, generieren schließlich einen Aufruf der Änderungsjournalsoftware, wenn die Datei geschlossen wird. Wenn Ihr DeviceIoControl-Aufruf darauf wartet, dass die Datei geschlossen wird, wird durch diesen Aufruf wiederum der DeviceIoControl-Aufruf zurückgegeben. Für den Fall, dass eine Datei oder ein Verzeichnis vor einem Volumefehler, Einem Betriebssystemfehler oder dem Herunterfahren nicht geschlossen wird, erfolgt beim nächsten Einbinden des Volumes ein Bereinigungsaufruf der Änderungsjournalsoftware. Der Aufruf erfolgt auch dann, wenn ein zwischenzeitlicher Systemneustart erfolgt.

Legen Sie ReturnOnlyOnClose auf Null fest, um bei der ersten Protokollierung jeder Änderung eine Benachrichtigung zu erhalten, sowie bei der Bereinigung.

Unabhängig davon, ob ReturnOnlyOnClose null oder ungleich null ist, sind die beim Bereinigungsprotokoll im Änderungsjournal generierten Datensätze alle Gründe für USN-Änderungen, die an der Datei oder dem Verzeichnis aufgetreten sind. Jedes Mal, wenn ein endgültiger Schließvorgang für ein Element auftritt, wird ein USN-Schließendatensatz in das Änderungsjournal geschrieben, und die ReasonMask-Flags für das Element werden zurückgesetzt.

Für eine Datei oder ein Verzeichnis, für die keine Benutzerdaten vorhanden sind (z. B. ein eingebundener Ordner), erfolgt der letzte Schließenvorgang, wenn die CloseHandle-Funktion im letzten Benutzerhandle für das Element aufgerufen wird.

Timeout

Der Timeoutwert in Sekunden, der mit dem BytesToWaitFor-Element verwendet wird, um dem Betriebssystem mitzuteilen, was zu tun ist, wenn der FSCTL_READ_USN_JOURNAL Vorgang mehr Daten anfordert, als im Änderungsjournal vorhanden sind.

Wenn Timeout null und BytesToWaitFor ungleich null ist und der FSCTL_READ_USN_JOURNAL Vorgangsaufruf das Ende des Änderungsjournals erreicht, ohne die zurückzugebenden Daten zu finden, wartet FSCTL_READ_USN_JOURNAL , bis BytesToWaitFor-Bytes der ungefilterten Daten dem Änderungsjournal hinzugefügt wurden, und ruft dann die angegebenen Datensätze ab.

Wenn Timeout ungleich null und BytesToWaitFor ungleich null ist und der FSCTL_READ_USN_JOURNAL Vorgangsaufruf das Ende des Änderungsjournals erreicht, ohne die zurückgegebenen Daten zu finden, wartet FSCTL_READ_USN_JOURNALTimeoutsekunden und versucht dann, die angegebenen Datensätze zurückzugeben. Nach Timeoutsekunden ruft FSCTL_READ_USN_JOURNAL alle Datensätze ab, die innerhalb des angegebenen Bereichs verfügbar sind.

In beiden Fällen werden nach dem Timeout alle neuen Daten verarbeitet, die an das Änderungsjournal angefügt werden. Wenn immer noch keine Datensätze aus der angegebenen Menge zurückgegeben werden sollen, wird der Timeoutzeitraum wiederholt. In diesem Modus bleibt FSCTL_READ_USN_JOURNAL ausstehend, bis mindestens ein Datensatz zurückgegeben oder E/A abgebrochen wird.

Wenn BytesToWaitFor null ist, wird timeout ignoriert. Timeout wird auch für asynchron geöffnete Handles ignoriert.

BytesToWaitFor

Die Anzahl der Bytes der ungefilterten Daten, die dem Änderungsjournal hinzugefügt wurden. Verwenden Sie diesen Wert mit Timeout , um dem Betriebssystem mitzuteilen, was zu tun ist, wenn der FSCTL_READ_USN_JOURNAL Vorgang mehr Daten anfordert, als im Änderungsjournal vorhanden sind.

Wenn BytesToWaitFor null ist, wird timeout ignoriert. In diesem Fall wird der FSCTL_READ_USN_JOURNAL-Vorgang immer erfolgreich zurückgegeben, wenn das Ende der Änderungsjournaldatei gefunden wird. Außerdem wird der USN abgerufen, der für den nächsten FSCTL_READ_USN_JOURNAL-Vorgang verwendet werden soll. Wenn die zurückgegebene nächste USN mit der angegebenen StartUsn übereinstimmt, sind keine Datensätze verfügbar. Der aufrufende Prozess sollte FSCTL_READ_USN_JOURNAL nicht sofort wieder verwenden.

Da die zurückgegebene Datenmenge nicht vorhergesagt werden kann, wenn BytesToWaitFor null ist, besteht die Gefahr, dass der Ausgabepuffer überläuft. Um dieses Risiko zu verringern, geben Sie in wiederholten FSCTL_READ_USN_JOURNAL Vorgängen einen BytesToWaitFor-Wert ungleich null an, bis alle Datensätze im Änderungsjournal erschöpft sind. Geben Sie dann null an, um auf neue Datensätze zu warten.

Alternativ können Sie den lpBytesReturned-Parameter von DeviceIoControl im FSCTL_READ_USN_JOURNAL-Vorgangsaufruf verwenden, um die verfügbare Datenmenge zu bestimmen, den Ausgabepuffer (mit Platz für neue Datensätze) neu zu versehen und DeviceIoControl erneut aufzurufen.

UsnJournalID

Der Bezeichner für die Instanz des Journals, die für das Volume aktuell ist.

Das NTFS-Dateisystem kann das Einfügen von Ereignissen im Änderungsjournal versäumen, wenn das Änderungsjournal beendet und neu gestartet oder gelöscht und neu erstellt wird. Wenn eines dieser Ereignisse auftritt, gibt das NTFS-Dateisystem dem Journal einen neuen Bezeichner. Wenn der Journalbezeichner nicht mit dem aktuellen Journalbezeichner übereinstimmt, schlägt der Aufruf von DeviceIoControl fehl und gibt einen entsprechenden Fehlercode zurück. Um den neuen Journalbezeichner abzurufen, rufen Sie DeviceIoControl mit dem vorgang FSCTL_QUERY_USN_JOURNAL auf.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Kopfzeile winioctl.h (windows.h einschließen)

Weitere Informationen

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD