Funzione ReadDirectoryChangesW (winbase.h)

Articolo
08/27/2023

Recupera informazioni che descrivono le modifiche all'interno della directory specificata. La funzione non segnala le modifiche apportate alla directory specificata.

Per tenere traccia delle modifiche in un volume, vedere Modificare i journal.

Sintassi

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
);

Parametri

[in] hDirectory

Handle della directory da monitorare. Questa directory deve essere aperta con il diritto di accesso FILE_LIST_DIRECTORY o un diritto di accesso, ad esempio GENERIC_READ che include il diritto di accesso FILE_LIST_DIRECTORY .

[out] lpBuffer

Puntatore al buffer formattato con allineamento DWORD in cui devono essere restituiti i risultati di lettura. La struttura di questo buffer è definita dalla struttura FILE_NOTIFY_INFORMATION . Questo buffer viene riempito in modo sincrono o asincrono, a seconda della modalità di apertura della directory e del valore assegnato al parametro lpOverlapped . Per altre informazioni, vedere la sezione Osservazioni.

[in] nBufferLength

Dimensione del buffer a cui punta il parametro lpBuffer , in byte.

[in] bWatchSubtree

Se questo parametro è TRUE, la funzione monitora l'albero di directory rooted nella directory specificata. Se questo parametro è FALSE, la funzione monitora solo la directory specificata dal parametro hDirectory .

[in] dwNotifyFilter

Criteri di filtro controllati dalla funzione per determinare se l'operazione di attesa è stata completata. 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 file.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Qualsiasi modifica del nome della directory nella directory o nel sottoalbero watched causa 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	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_LAST_ACCESS 0x00000020	Qualsiasi modifica apportata all'ora dell'ultimo accesso dei file nella directory o nel sottoalbero watched causa la restituzione di un'operazione di attesa delle notifiche di modifica.
FILE_NOTIFY_CHANGE_CREATION 0x00000040	Qualsiasi modifica apportata all'ora di creazione dei file nella directory o nel sottoalbero watched causa la restituzione di un'operazione di attesa delle notifiche di modifica.
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.

[out, optional] lpBytesReturned

Per le chiamate sincrone, questo parametro riceve il numero di byte trasferiti nel parametro lpBuffer . Per le chiamate asincrone, questo parametro non è definito. Per recuperare il numero di byte trasferiti, è necessario utilizzare una tecnica di notifica asincrona.

[in, out, optional] lpOverlapped

Puntatore a una struttura OVERLAPPED che fornisce dati da utilizzare durante l'operazione asincrona. In caso contrario, questo valore è NULL. I membri Offset e OffsetHigh di questa struttura non vengono utilizzati.

[in, optional] lpCompletionRoutine

Puntatore a una routine di completamento da chiamare quando l'operazione è stata completata o annullata e il thread chiamante si trova in uno stato di attesa di avviso. Per altre informazioni su questa routine di completamento, vedere FileIOCompletionRoutine.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero. Per le chiamate sincrone, significa che l'operazione è riuscita. Per le chiamate asincrone, indica che l'operazione è stata accodata correttamente.

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

Se il redirector di rete o il file system di destinazione non supporta questa operazione, la funzione ha esito negativo con ERROR_INVALID_FUNCTION.

Commenti

Per ottenere un handle in una directory, usare la funzione CreateFile con il flag FILE_FLAG_BACKUP_SEMANTICS .

Una chiamata a ReadDirectoryChangesW può essere completata in modo sincrono o asincrono. Per specificare il completamento asincrono, aprire la directory con CreateFile come illustrato in precedenza, ma specificare anche l'attributo FILE_FLAG_OVERLAPPED nel parametro dwFlagsAndAttributes . Specificare quindi una struttura OVERLAPPED quando si chiama ReadDirectoryChangesW.

Quando si chiama ReadDirectoryChangesW per la prima volta, il sistema alloca un buffer per archiviare le informazioni sulle modifiche. Questo buffer è associato all'handle di directory fino a quando non viene chiuso e le relative dimensioni non cambiano durante la durata. Le modifiche alla directory che si verificano tra le chiamate a questa funzione vengono aggiunte al buffer e quindi restituite con la chiamata successiva. Se l'overflow del buffer, ReadDirectoryChangesW restituirà comunque true, ma l'intero contenuto del buffer viene eliminato e il parametro lpBytesReturned sarà zero, che indica che il buffer era troppo piccolo per contenere tutte le modifiche apportate.

Al termine del completamento sincrono, il parametro lpBuffer è un buffer formattato e il numero di byte scritti nel buffer è disponibile in lpBytesReturned. Se il numero di byte trasferiti è pari a zero, il buffer è troppo grande per consentire al sistema di allocare o troppo piccolo per fornire informazioni dettagliate su tutte le modifiche apportate nella directory o nel sottoalbero. In questo caso, è necessario calcolare le modifiche enumerando la directory o il sottoalbero.

Per il completamento asincrono, è possibile ricevere una notifica in uno dei tre modi seguenti:

Uso della funzione GetOverlappedResult . Per ricevere una notifica tramite GetOverlappedResult, non specificare una routine di completamento nel parametro lpCompletionRoutine . Assicurarsi di impostare il membro hEvent della struttura OVERLAPPED su un evento univoco.
Uso della funzione GetQueuedCompletionStatus . Per ricevere una notifica tramite GetQueuedCompletionStatus, non specificare una routine di completamento in lpCompletionRoutine. Associare l'handle di directory hDirectory a una porta di completamento chiamando la funzione CreateIoCompletionPort .
Utilizzo di una routine di completamento. Per ricevere una notifica tramite una routine di completamento, non associare la directory a una porta di completamento. Specificare una routine di completamento in lpCompletionRoutine. Questa routine viene chiamata ogni volta che l'operazione è stata completata o annullata mentre il thread si trova in uno stato di attesa di avviso. Il membro hEvent della struttura OVERLAPPED non viene usato dal sistema, quindi è possibile usarlo autonomamente.

Per altre informazioni, vedere I/O sincrono e asincrono.

ReadDirectoryChangesW ha esito negativo con ERROR_INVALID_PARAMETER quando la lunghezza del buffer è maggiore di 64 KB e l'applicazione monitora una directory in rete. Ciò è dovuto a una limitazione delle dimensioni dei pacchetti con i protocolli di condivisione file sottostanti.

ReadDirectoryChangesW ha esito negativo con ERROR_NOACCESS quando il buffer non è allineato su un limite DWORD .

ReadDirectoryChangesW ha esito negativo con ERROR_NOTIFY_ENUM_DIR quando il sistema non è riuscito a registrare tutte le modifiche apportate alla directory. In questo caso, è necessario calcolare le modifiche enumerando la directory o il sottoalbero.

Se il file è stato aperto usando il nome breve, è possibile ricevere notifiche di modifica per il nome breve.

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 di scalabilità orizzontale (SO)	Sì
File system del volume condiviso cluster (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Operazioni transazionate

Se è presente una transazione associata all'handle di directory, le notifiche seguono le regole di isolamento delle transazioni appropriate.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll