FindFirstChangeNotificationA-Funktion (fileapi.h)
Erstellt ein Änderungsbenachrichtigungshandle und richtet anfängliche Änderungsbenachrichtigungsfilterbedingungen ein. Ein Warten auf ein Benachrichtigungshandle ist erfolgreich, wenn eine Änderung, die den Filterbedingungen entspricht, im angegebenen Verzeichnis oder in der angegebenen Unterstruktur auftritt. Die Funktion meldet keine Änderungen am angegebenen Verzeichnis selbst.
Diese Funktion gibt nicht die Änderung an, die die Wartebedingung erfüllt hat. Verwenden Sie zum Abrufen von Informationen zu der spezifischen Änderung im Rahmen der Benachrichtigung die
ReadDirectoryChangesW-Funktion .
Syntax
HANDLE FindFirstChangeNotificationA(
[in] LPCSTR lpPathName,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter
);
Parameter
[in] lpPathName
Der vollständige Pfad des zu überwachenden Verzeichnisses.
Dies kann kein relativer Pfad oder eine leere Zeichenfolge sein.
Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.
Tipp
Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .
[in] bWatchSubtree
Wenn dieser Parameter TRUE ist, überwacht die Funktion die Verzeichnisstruktur, die im angegebenen Verzeichnis verwurzelt ist. wenn es FALSE ist, überwacht es nur das angegebene Verzeichnis.
[in] dwNotifyFilter
Die Filterbedingungen, die eine Änderungsbenachrichtigungswarte erfüllen. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handeln.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für ein Suchänderungsbenachrichtigungsobjekt.
Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Bemerkungen
Die Wartefunktionen können das angegebene Verzeichnis oder die angegebene Unterstruktur mithilfe des von der FindFirstChangeNotification-Funktion zurückgegebenen Handle überwachen. Eine Wartezeit ist erfüllt, wenn eine der Filterbedingungen im überwachten Verzeichnis oder in der überwachten Unterstruktur auftritt.
Nachdem die Wartezeit abgeschlossen wurde, kann die Anwendung auf diese Bedingung reagieren und die Überwachung des Verzeichnisses fortsetzen, indem sie die FindNextChangeNotification-Funktion und die entsprechende Wartefunktion aufruft. Wenn der Handle nicht mehr benötigt wird, kann es mithilfe der Funktion FindCloseChangeNotification geschlossen werden.
Beim Aufrufen von FindFirstChangeNotification für ein Remotedateisystem werden möglicherweise keine Benachrichtigungen zurückgegeben.
Verhalten symbolischer Verknüpfungen: Wenn der Pfad auf einen symbolischen Link verweist, wird das Benachrichtigungshandle für das Ziel erstellt.
Wenn eine Anwendung registriert ist, um Änderungsbenachrichtigungen für ein Verzeichnis zu erhalten, das symbolische Links enthält, wird die Anwendung nur benachrichtigt, wenn die symbolischen Verknüpfungen geändert wurden, nicht die Zieldateien.
In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| Server Message Block (SMB) 3.0-Protokoll | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Horizontalskalieren von Dateifreigaben (SO) | Ja |
| Freigegebenes Clustervolume-Dateisystem (CsvFS) | Siehe Bemerkung |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Bei der Anwendung kann es zu falsch positiven Ergebnissen bei CsvFs zum Anhalten/Fortsetzen kommen.
Beispiele
Ein Beispiel finden Sie unter Abrufen von Verzeichnis Change_Notifications.
Hinweis
Der fileapi.h-Header definiert FindFirstChangeNotification als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |