ReadDirectoryChangesW-Funktion (winbase.h)
Ruft Informationen ab, die die Änderungen innerhalb des angegebenen Verzeichnisses beschreiben. Die Funktion meldet keine Änderungen an dem angegebenen Verzeichnis selbst.
Informationen zum Nachverfolgen von Änderungen auf 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 Verzeichnis, das überwacht werden soll. Dieses Verzeichnis muss mit dem FILE_LIST_DIRECTORY Zugriffsrecht oder einem Zugriffsrecht wie GENERIC_READ geöffnet werden, das das zugriffsrecht FILE_LIST_DIRECTORY enthält.
[out] lpBuffer
Ein Zeiger auf den formatierten DWORD-ausgerichteten Puffer, in dem die Leseergebnisse zurückgegeben werden sollen. Die Struktur dieses Puffers wird durch die FILE_NOTIFY_INFORMATION Struktur definiert. Dieser Puffer wird entweder synchron oder asynchron ausgefü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 verankert ist. Wenn dieser Parameter FALSCH 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 mindestens eine der folgenden Werte sein.
[out, optional] lpBytesReturned
Für synchrone Aufrufe empfängt dieser Parameter die Anzahl der Bytes, die in den lpBuffer-Parameter übertragen werden. Bei asynchronen Aufrufen ist dieser Parameter nicht definiert. Sie müssen eine asynchrone Benachrichtigungstechnik 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 Abschlussroutine, die aufgerufen werden soll, wenn der Vorgang abgeschlossen oder abgebrochen wurde, und der aufrufende Thread befindet sich in einem warnbaren Wartezustand. Weitere Informationen zu dieser Abschlussroutine 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 gibt dies an, 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.
Bemerkungen
Verwenden Sie zum Abrufen eines Handles zu einem Verzeichnis die CreateFile-Funktion mit dem FILE_FLAG_BACKUP_SEMANTICS Flag.
Ein Aufruf von ReadDirectoryChangesW kann synchron oder asynchron abgeschlossen werden. Um asynchrone Fertigstellung anzugeben, öffnen Sie das Verzeichnis mit CreateFile wie oben dargestellt, geben aber zusätzlich das FILE_FLAG_OVERLAPPED Attribut im Parameter dwFlagsAndAttributes an. Geben Sie dann eine ÜBERLAPPENDE 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 wird und seine Größe während der Lebensdauer nicht geändert wird. 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 Parameter lpBytesReturned ist null, was angibt, dass der Puffer zu klein war, um alle vorgenommenen Änderungen zu halten.
Nach erfolgreicher synchroner Fertigstellung ist der lpBuffer-Parameter ein formatierter Puffer und die Anzahl der bytes, die in den Puffer geschrieben wurden, ist in lpBytesReturned verfügbar. Wenn die Anzahl der übertragenen Bytes null ist, war der Puffer entweder zu groß für das System, um detaillierte Informationen zu allen im Verzeichnis oder in der Unterstruktur aufgetretenen Änderungen bereitzustellen. In diesem Fall sollten Sie die Änderungen berechnen, indem Sie das Verzeichnis oder die Unterstruktur aufzählen.
Bei asynchroner Fertigstellung können Sie Benachrichtigungen auf eine von drei Arten empfangen:
- Verwenden der GetOverlappedResult-Funktion . Wenn Sie Benachrichtigungen über GetOverlappedResult empfangen möchten, geben Sie keine Abschlussroutine im lpCompletionRoutine-Parameter an. Achten Sie darauf, das hEvent-Element der ÜBERLAPPENDEN Struktur auf ein eindeutiges Ereignis festzulegen.
- Verwenden der GetQueuedCompletionStatus-Funktion . Um Benachrichtigungen über GetQueuedCompletionStatus zu erhalten, geben Sie keine Abschlussroutine in lpCompletionRoutine an. Ordnen Sie das Verzeichnis handle hDirectory einem Abschlussport zu, indem Sie die Funktion CreateIoCompletionPort aufrufen.
- Verwenden einer Abschlussroutine. Wenn Sie Benachrichtigungen über eine Abschlussroutine empfangen möchten, ordnen Sie das Verzeichnis nicht einem Abschlussport zu. Geben Sie eine Abschlussroutine in lpCompletionRoutine an. Diese Routine wird aufgerufen, wenn der Vorgang abgeschlossen oder abgebrochen wurde, während sich der Thread in einem warnungsfähigen Wartezustand befindet. Das hEvent-Element der ÜBERLAPPENDEN Struktur wird vom System nicht verwendet, sodass Sie es selbst verwenden können.
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 liegt an einer Paketgrößesbeschränkung mit den zugrunde liegenden Dateifreigabeprotokollen.
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 im Verzeichnis aufzeichnen konnte. In diesem Fall sollten Sie die Änderungen berechnen, indem Sie das Verzeichnis oder die Unterstruktur aufzählen.
Wenn Sie die Datei mit dem Kurznamen geöffnet haben, können Sie Änderungsbenachrichtigungen für den Kurznamen erhalten.
In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| Servernachrichtenblock (SMB) 3.0-Protokoll | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Skalierungsdateifreigaben (SO) | Ja |
| Cluster Shared Volume File System (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Transaktionsvorgänge
Wenn eine Transaktion an den Verzeichnishandpunkt 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 (enthalten Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |