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 |
|---|---|
|
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. |
|
Die Datei oder das Verzeichnis ist geschlossen. |
|
Der Komprimierungsstatus der Datei oder des Verzeichnisses wird von oder in komprimiert geändert. |
|
Die Datei oder das Verzeichnis wird hinzugefügt. |
|
Daten in der Datei oder im Verzeichnis werden überschrieben. |
|
Die Datei oder das Verzeichnis wird abgeschnitten. |
|
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. |
|
Die Datei oder das Verzeichnis wird verschlüsselt oder entschlüsselt. |
|
Die Datei oder das Verzeichnis wird zum ersten Mal erstellt. |
|
Die Datei oder das Verzeichnis wird gelöscht. |
|
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. |
|
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.) |
|
Mindestens ein benannter Datenstrom für die Datei wurde hinzugefügt. |
|
Daten in einem oder mehreren benannten Datenströmen für die Datei werden überschrieben. |
|
Mindestens ein benannter Datenstrom für die Datei wird abgeschnitten. |
|
Der Objektbezeichner der Datei oder des Verzeichnisses wird geändert. |
|
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. |
|
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. |
|
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. |
|
An den Zugriffsberechtigungen für die Datei oder das Verzeichnis wird eine Änderung vorgenommen. |
|
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) |