Funzione FindFirstChangeNotificationA (fileapi.h)

Articolo
11/20/2024

Crea un handle di notifica delle modifiche e configura le condizioni iniziali del filtro delle notifiche delle modifiche. 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 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ò trattarsi di un percorso relativo o di una stringa vuota.

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

Mancia

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, percorsi e spazi dei nomi.

[in] bWatchSubtree

Se questo parametro è TRUE, la funzione monitora l'albero della directory rooted nella directory specificata; se è FALSE, esegue il monitoraggio solo della 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	Qualsiasi modifica del nome file nella directory o nel sottoalbero watched causa la restituzione di un'operazione di attesa delle notifiche di modifica. Le modifiche includono la ridenominazione, la creazione o l'eliminazione di un nome file.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Qualsiasi modifica del nome di directory nella directory o nel sottoalbero sorvegliato determina la restituzione di un'operazione di attesa delle notifiche di modifica. Le modifiche includono la creazione o l'eliminazione di una directory.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Qualsiasi modifica dell'attributo nella directory o nel sottoalbero watched causa la restituzione di un'operazione di attesa delle notifiche di modifica.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Qualsiasi modifica delle dimensioni dei file nella directory o nel sottoalbero watched causa la restituzione di un'operazione di attesa delle notifiche di modifica. Il sistema operativo rileva una modifica delle dimensioni del file solo quando il file viene scritto sul disco. Per i sistemi operativi che usano una memorizzazione nella cache estesa, il rilevamento si verifica solo quando la cache è sufficientemente scaricata.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Qualsiasi modifica apportata all'ultima fase di scrittura dei file nella directory o nel sottoalbero watched fa sì che venga restituita un'operazione di attesa delle notifiche di modifica. Il sistema operativo rileva una modifica all'ultima fase di scrittura solo quando il file viene scritto sul disco. Per i sistemi operativi che usano una memorizzazione nella cache estesa, il rilevamento si verifica solo quando la cache è 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 delle notifiche di modifica.

Valore restituito

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

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

Osservazioni

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.

È possibile che le notifiche non vengano restituite quando si chiama FindFirstChangeNotification per un file system remoto.

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

Se un'applicazione è stata registrata per ricevere notifiche di modifica per una directory contenente 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	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
Cluster Shared Volume File System (CsvFS)	Vedere la nota
Resilient File System (ReFS)	Sì

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

Esempi

Per un esempio, vedere Ottenere la directory Change_Notifications.

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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	fileapi.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll

Vedere anche

funzioni di gestione directory di

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW

Condividi tramite