Freigeben über


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.

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. Die Änderungen umfassen Umbenennen, Erstellen oder Löschen eines Dateinamens.
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_SECURITY
0x00000100
Jede Änderung der Sicherheitsbeschreibung im überwachten Verzeichnis oder Unterbaum führt dazu, dass ein Wartevorgang für Änderungsbenachrichtigungen zurückgegeben wird.

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

Siehe auch

Verzeichnisverwaltungsfunktionen

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW