ReadDirectoryChangesW-Funktion (winbase.h)

Artikel
08/27/2023

Hiermit werden Informationen abgerufen, die die Änderungen innerhalb des angegebenen Verzeichnisses beschreiben. Die Funktion meldet keine Änderungen am angegebenen Verzeichnis selbst.

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

Syntax

BOOL ReadDirectoryChangesW(
  [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
);

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 die Leseergebnisse zurückgegeben werden sollen. Die Struktur dieses Puffers wird durch die FILE_NOTIFY_INFORMATION-Struktur definiert. 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 in Bytes verweist.

[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.

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 ReadDirectoryChangesW 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 ReadDirectoryChangesW aufrufen.

Wenn Sie ReadDirectoryChangesW 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 ReadDirectoryChangesW 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.

ReadDirectoryChangesW 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.

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

ReadDirectoryChangesW 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.

Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Transaktionierte Vorgänge

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll