Funzione FindFirstChangeNotificationA (fileapi.h)

Articolo
06/02/2023

Crea un handle di notifica delle modifiche e configura le condizioni di filtro delle modifiche iniziali. Un'attesa su un handle di notifica ha esito positivo quando si verifica una modifica corrispondente alle condizioni di filtro nella directory o nel sottoalbero specificato. La funzione non segnala le modifiche apportate alla directory specificata stessa.

Questa funzione non indica la modifica che ha soddisfatto la condizione di attesa. Per recuperare informazioni sulla modifica specifica come parte della notifica, usare
Funzione ReadDirectoryChangesW .

Sintassi

HANDLE FindFirstChangeNotificationA(
  [in] LPCSTR lpPathName,
  [in] BOOL   bWatchSubtree,
  [in] DWORD  dwNotifyFilter
);

Parametri

[in] lpPathName

Percorso completo della directory da controllare.

Non può essere un percorso relativo o una stringa vuota.

Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, prependo "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.

Suggerimento

A partire da Windows 10, versione 1607, è possibile scegliere di rimuovere la limitazione MAX_PATH senza pre sospeso "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima lunghezza percorso" di nomi, nomi, percorsi e spazi dei nomi .

[in] bWatchSubtree

Se questo parametro è TRUE, la funzione monitora l'albero della directory radicato nella directory specificata; se è FALSE, monitora solo la directory specificata.

[in] dwNotifyFilter

Condizioni di filtro che soddisfano un'attesa di notifica delle modifiche. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	In caso di modifica del nome file nella directory o nel sottoalbero sotto osservazione verrà restituita un'operazione di attesa notifica di cambiamento. Le modifiche includono la ridenominazione, la creazione o l'eliminazione di un nome file.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Qualsiasi modifica del nome della directory o del sottoalbero guardato causa la restituzione di un'operazione di attesa della notifica delle modifiche. Le modifiche includono la creazione o l'eliminazione di una directory.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	In caso di modifica degli attributi nella directory o nel sottoalbero sotto osservazione verrà restituita un'operazione di attesa notifica di cambiamento.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	In caso di modifica delle dimensioni del file nella directory o nel sottoalbero sotto osservazione verrà restituita un'operazione di attesa notifica di cambiamento. Il sistema operativo rileva una modifica nelle dimensioni del file solo quando il file viene scritto sul disco. Per i sistemi operativi che richiedono una completa memorizzazione nella cache, il rilevamento si verifica solo quando la cache viene sufficientemente scaricata.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	In caso di modifica dell'ultima ora di scrittura di file nella directory o nel sottoalbero sotto osservazione verrà restituita un'operazione di attesa notifica di cambiamento. Il sistema operativo rileva una modifica all'ora dell'ultima scrittura solo quando il file viene scritto nel disco. Per i sistemi operativi che richiedono una completa memorizzazione nella cache, il rilevamento si verifica solo quando la cache viene sufficientemente scaricata.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Qualsiasi modifica del descrittore di sicurezza nella directory o nel sottoalbero watched causa la restituzione di un'operazione di attesa della notifica delle modifiche.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per un oggetto di notifica di modifica della ricerca.

Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Le funzioni di attesa possono monitorare la directory o il sottoalbero specificato usando l'handle restituito dalla funzione FindFirstChangeNotification . Un'attesa viene soddisfatta quando si verifica una delle condizioni di filtro nella directory monitorata o nel sottoalbero.

Dopo aver soddisfatto l'attesa, l'applicazione può rispondere a questa condizione e continuare a monitorare la directory chiamando la funzione FindNextChangeNotification e la funzione di attesa appropriata. Quando l'handle non è più necessario, può essere chiuso usando la funzione FindCloseChangeNotification .

Le notifiche potrebbero non essere restituite quando si chiama FindFirstChangeNotification per un file system remoto.

Comportamento di collegamento simbolico: se il percorso punta a un collegamento simbolico, l'handle di notifica viene creato per la destinazione.

Se un'applicazione ha registrato per ricevere notifiche di modifica per una directory che contiene collegamenti simbolici, l'applicazione riceve una notifica solo quando i collegamenti simbolici sono stati modificati, non i file di destinazione.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
File system del volume condiviso del cluster (CsvFS)	Vedere l'osservazione
File system resiliente (ReFS)	Sì

L'applicazione potrebbe riscontrare falsi positivi in csvFs pausa/ripresa.

Esempi

Per un esempio, vedere Ottenere Change_Notifications directory.

Nota

L'intestazione fileapi.h definisce FindFirstChangeNotification come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	fileapi.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll