ReadDirectoryChangesW-Funktion (winbase.h)
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.
[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.
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 |