ReadDirectoryChangesExW-Funktion (winbase.h)

Artikel
03/03/2024

Hiermit werden Informationen abgerufen, die die Änderungen innerhalb des angegebenen Verzeichnisses beschreiben, das erweiterte Informationen enthalten kann, wenn dieser Informationstyp angegeben ist. Die Funktion meldet keine Änderungen am angegebenen Verzeichnis selbst.

Informationen zum Nachverfolgen von Änderungen an einem Volume finden Sie unter Änderungsjournale.

Syntax

BOOL ReadDirectoryChangesExW(
  [in]                HANDLE                                  hDirectory,
  [out]               LPVOID                                  lpBuffer,
  [in]                DWORD                                   nBufferLength,
  [in]                BOOL                                    bWatchSubtree,
  [in]                DWORD                                   dwNotifyFilter,
  [out, optional]     LPDWORD                                 lpBytesReturned,
  [in, out, optional] LPOVERLAPPED                            lpOverlapped,
  [in, optional]      LPOVERLAPPED_COMPLETION_ROUTINE         lpCompletionRoutine,
  [in]                READ_DIRECTORY_NOTIFY_INFORMATION_CLASS ReadDirectoryNotifyInformationClass
);

Parameter

[in] hDirectory

Ein Handle für das zu überwachende Verzeichnis. Dieses Verzeichnis muss mit dem zugriffsrecht FILE_LIST_DIRECTORY oder einem Zugriffsrecht wie GENERIC_READ geöffnet werden, das das FILE_LIST_DIRECTORY-Zugriffsrecht enthält.

[out] lpBuffer

Ein Zeiger auf den DWORD-ausgerichteten formatierten Puffer, in dem ReadDirectoryChangesExW die Leseergebnisse zurückgeben soll. Die Struktur dieses Puffers wird durch die FILE_NOTIFY_EXTENDED_INFORMATION-Struktur definiert, wenn der Wert des ReadDirectoryNotifyInformationClass-ParametersReadDirectoryNotifyExtendedInformation lautet, oder durch die FILE_NOTIFY_INFORMATION-Struktur , wenn ReadDirectoryNotifyInformationClassreadDirectoryNotifyInformation Ist.

Dieser Puffer wird synchron oder asynchron gefüllt, je nachdem, wie das Verzeichnis geöffnet wird und welcher Wert dem lpOverlapped-Parameter zugewiesen wird. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in] nBufferLength

Die Größe des Puffers, auf den der lpBuffer-Parameter verweist, in Bytes.

[in] bWatchSubtree

Wenn dieser Parameter TRUE ist, überwacht die Funktion die Verzeichnisstruktur, die im angegebenen Verzeichnis verwurzelt ist. Wenn dieser Parameter FALSE ist, überwacht die Funktion nur das vom hDirectory-Parameter angegebene Verzeichnis.

[in] dwNotifyFilter

Die Filterkriterien, die die Funktion überprüft, um festzustellen, ob der Wartevorgang abgeschlossen wurde. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Jede Dateinamenänderung im überwachten Verzeichnis oder Unterverzeichnis bewirkt, dass ein Wartevorgang für die Änderungsbenachrichtigung zurückgegeben wird. Änderungen umfassen das Umbenennen, Erstellen oder Löschen einer Datei.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Jede Änderung des Verzeichnisnamens im überwachten Verzeichnis oder in der überwachten Unterstruktur führt dazu, dass ein Wartevorgang für Änderungsbenachrichtigungen zurückgegeben wird. Änderungen umfassen das Erstellen oder Löschen eines Verzeichnisses.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Jede Attributänderung im überwachten Verzeichnis oder Unterverzeichnis bewirkt, dass ein Wartevorgang für die Änderungsbenachrichtigung zurückgegeben wird.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Jede Dateigrößenenänderung im überwachten Verzeichnis oder Unterverzeichnis bewirkt, dass ein Wartevorgang für die Änderungsbenachrichtigung zurückgegeben wird. Das Betriebssystem erkennt eine Änderung der Dateigröße nur, wenn die Datei auf den Datenträger geschrieben wird. Für Betriebssysteme, die umfangreiche Zwischenspeicherung verwenden, tritt die Erkennung tritt nur auf, wenn der Cache genug geleert wird.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Jede Änderung am letzten Schreiben von Dateien im überwachten Verzeichnis oder Unterverzeichnis bewirkt, dass ein Wartevorgang für die Änderungsbenachrichtigung zurückgegeben wird. Das Betriebssystem erkennt eine Änderung des letzten Schreibzeitpunkts nur, wenn die Datei auf den Datenträger geschrieben wird. Für Betriebssysteme, die umfangreiche Zwischenspeicherung verwenden, tritt die Erkennung tritt nur auf, wenn der Cache genug geleert wird.
FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020	Jede Änderung der letzten Zugriffszeit von Dateien im überwachten Verzeichnis oder unterbaum bewirkt, dass ein Wartevorgang für Änderungsbenachrichtigungen zurückgegeben wird.
FILE_NOTIFY_CHANGE_CREATION 0x00000040	Jede Änderung der Erstellungszeit von Dateien im überwachten Verzeichnis oder Unterbaum führt dazu, dass ein Wartevorgang für Änderungsbenachrichtigungen zurückgegeben wird.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Jede Änderung der Sicherheitsbeschreibung im überwachten Verzeichnis oder Unterbaum führt dazu, dass ein Wartevorgang für Änderungsbenachrichtigungen zurückgegeben wird.

[out, optional] lpBytesReturned

Bei synchronen Aufrufen empfängt dieser Parameter die Anzahl von Bytes, die in den lpBuffer-Parameter übertragen werden. Bei asynchronen Aufrufen ist dieser Parameter nicht definiert. Sie müssen eine asynchrone Benachrichtigungsmethode verwenden, um die Anzahl der übertragenen Bytes abzurufen.

[in, out, optional] lpOverlapped

Ein Zeiger auf eine ÜBERLAPPENDE Struktur, die Daten bereitstellt, die während des asynchronen Vorgangs verwendet werden sollen. Andernfalls ist dieser Wert NULL. Die Elemente Offset und OffsetHigh dieser Struktur werden nicht verwendet.

[in, optional] lpCompletionRoutine

Ein Zeiger auf eine Vervollständigungsroutine, die aufgerufen werden soll, wenn der Vorgang abgeschlossen oder abgebrochen wurde und sich der aufrufende Thread in einem warnbaren Wartezustand befindet. Weitere Informationen zu dieser Vervollständigungsroutine finden Sie unter FileIOCompletionRoutine.

[in] ReadDirectoryNotifyInformationClass

Der Typ der Informationen, die ReadDirectoryChangesExW in den Puffer schreiben soll, auf den der lpBuffer-Parameter verweist. Geben Sie ReadDirectoryNotifyInformation an, um anzugeben, dass die Informationen aus FILE_NOTIFY_INFORMATION-Strukturen bestehen sollen, oder ReadDirectoryNotifyExtendedInformation , um anzugeben, dass die Informationen aus FILE_NOTIFY_EXTENDED_INFORMATION Strukturen bestehen sollen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null. Bei synchronen Aufrufen bedeutet dies, dass der Vorgang erfolgreich war. Bei asynchronen Aufrufen bedeutet dies, dass der Vorgang erfolgreich in die Warteschlange gestellt wurde.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn der Netzwerkumleitungsor oder das Zieldateisystem diesen Vorgang nicht unterstützt, schlägt die Funktion mit ERROR_INVALID_FUNCTION fehl.

Hinweise

Um ein Handle für ein Verzeichnis abzurufen, verwenden Sie die CreateFile-Funktion mit dem flag FILE_FLAG_BACKUP_SEMANTICS .

Ein Aufruf von ReadDirectoryChangesExW kann synchron oder asynchron abgeschlossen werden. Um die asynchrone Vervollständigung anzugeben, öffnen Sie das Verzeichnis mit CreateFile , wie oben gezeigt, aber geben Sie zusätzlich das attribut FILE_FLAG_OVERLAPPED im dwFlagsAndAttributes-Parameter an. Geben Sie dann eine OVERLAPPED-Struktur an, wenn Sie ReadDirectoryChangesExW aufrufen.

Wenn Sie ReadDirectoryChangesExW zum ersten Mal aufrufen, weist das System einen Puffer zu, um Änderungsinformationen zu speichern. Dieser Puffer ist dem Verzeichnishandle zugeordnet, bis er geschlossen ist und seine Größe sich während seiner Lebensdauer nicht ändert. Verzeichnisänderungen, die zwischen Aufrufen dieser Funktion auftreten, werden dem Puffer hinzugefügt und dann mit dem nächsten Aufruf zurückgegeben. Wenn der Puffer überläuft, gibt ReadDirectoryChangesExW weiterhin true zurück, aber der gesamte Inhalt des Puffers wird verworfen, und der lpBytesReturned-Parameter ist 0, was angibt, dass ihr Puffer zu klein war, um alle aufgetretenen Änderungen aufzunehmen.

Nach erfolgreicher synchroner Fertigstellung ist der lpBuffer-Parameter ein formatierter Puffer, und die Anzahl der in den Puffer geschriebenen Bytes ist in lpBytesReturned verfügbar. Wenn die Anzahl der übertragenen Bytes 0 ist, war der Puffer entweder zu groß, um das System zuzuordnen, oder zu klein, um detaillierte Informationen zu allen Änderungen im Verzeichnis oder der Unterstruktur bereitzustellen. In diesem Fall sollten Sie die Änderungen berechnen, indem Sie das Verzeichnis oder die Unterstruktur auflisten.

Für die asynchrone Vervollständigung können Sie Benachrichtigungen auf eine von drei Arten empfangen:

Verwenden der GetOverlappedResult-Funktion . Um Benachrichtigungen über GetOverlappedResult zu erhalten, geben Sie keine Vervollständigungsroutine im lpCompletionRoutine-Parameter an. Legen Sie das hEvent-Element der OVERLAPPED-Struktur auf ein eindeutiges Ereignis fest.
Verwenden der GetQueuedCompletionStatus-Funktion . Um Benachrichtigungen über GetQueuedCompletionStatus zu erhalten, geben Sie keine Vervollständigungsroutine in lpCompletionRoutine an. Ordnen Sie das Verzeichnishandle hDirectory einem Vervollständigungsport zu, indem Sie die CreateIoCompletionPort-Funktion aufrufen.
Verwenden einer Vervollständigungsroutine. Um Benachrichtigungen über eine Vervollständigungsroutine zu erhalten, ordnen Sie das Verzeichnis nicht einem Vervollständigungsport zu. Geben Sie eine Vervollständigungsroutine in lpCompletionRoutine an. Diese Routine wird aufgerufen, wenn der Vorgang abgeschlossen oder abgebrochen wurde, während sich der Thread in einem warnbaren Wartezustand befindet. Das hEvent-Element der OVERLAPPED-Struktur wird vom System nicht verwendet, sodass Sie es selbst verwenden können.

Weitere Informationen finden Sie unter Synchrone und asynchrone E/A.

ReadDirectoryChangesExW schlägt mit ERROR_INVALID_PARAMETER fehl, wenn die Pufferlänge größer als 64 KB ist und die Anwendung ein Verzeichnis über das Netzwerk überwacht. Dies ist auf eine Paketgrößeseinschränkung mit den zugrunde liegenden Dateifreigabeprotokollen zurückzuführen.

ReadDirectoryChangesExW schlägt mit ERROR_NOACCESS fehl, wenn der Puffer nicht an einer DWORD-Grenze ausgerichtet ist.

ReadDirectoryChangesExW schlägt mit ERROR_NOTIFY_ENUM_DIR fehl, wenn das System nicht alle Änderungen am Verzeichnis aufzeichnen konnte. In diesem Fall sollten Sie die Änderungen berechnen, indem Sie das Verzeichnis oder die Unterstruktur auflisten.

Wenn Sie die Datei mit dem kurzen Namen geöffnet haben, können Sie Änderungsbenachrichtigungen für den kurzen Namen erhalten.

ReadDirectoryChangesExW wird derzeit nur für das NTFS-Dateisystem unterstützt.

Transaktionen

Wenn eine Transaktion an das Verzeichnishandle gebunden ist, folgen die Benachrichtigungen den entsprechenden Transaktionsisolationsregeln.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 10, Version 1709 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2019 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll