struttura READ_USN_JOURNAL_DATA_V0 (winioctl.h)
Contiene informazioni che definiscono un set di record del journal delle modifiche del numero di sequenza di aggiornamento (USN) da restituire al processo chiamante. Viene utilizzato dai codici di controllo FSCTL_QUERY_USN_JOURNAL e FSCTL_READ_USN_JOURNAL . Prima di Windows 8 e Windows Server 2012 questa struttura è stata denominata READ_USN_JOURNAL_DATA. Usare questo nome per la compilazione con SDK e compilatori meno recenti. Windows Server 2012 introdotta READ_USN_JOURNAL_DATA_V1 per supportare gli identificatori di file a 128 bit usati da ReFS.
Sintassi
typedef struct {
USN StartUsn;
DWORD ReasonMask;
DWORD ReturnOnlyOnClose;
DWORDLONG Timeout;
DWORDLONG BytesToWaitFor;
DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;
Members
StartUsn
USN in corrispondenza del quale iniziare a leggere il journal delle modifiche.
Per avviare l'operazione di lettura al primo record nel journal, impostare il membro StartUsn su zero. Poiché un USN è contenuto in ogni record journal, il buffer di output indica in quale record l'operazione di lettura è stata effettivamente avviata.
Per avviare l'operazione di lettura in corrispondenza di un record specifico, impostare StartUsn sul record USN.
Se viene specificato un USN diverso da zero minore del primo USN nel journal delle modifiche, si verifica un errore e viene restituito il codice di errore ERROR_JOURNAL_ENTRY_DELETED . Questo codice può indicare un caso in cui l'USN specificato è valido contemporaneamente ma è stato eliminato.
Per altre informazioni sull'esplorazione del buffer del journal delle modifiche restituito in READ_USN_JOURNAL_DATA_V0, vedere Walking a Buffer of Change Journal Records.For more information on navigating the change journal buffer returned in READ_USN_JOURNAL_DATA_V0, see Walking a Buffer of Change Journal Records.
ReasonMask
Maschera di flag, ogni flag che nota una modifica per cui il file o la directory ha un record nel journal delle modifiche. Per essere restituito in un'operazione di FSCTL_READ_USN_JOURNAL , un record del journal delle modifiche deve avere almeno uno di questi flag impostati.
L'elenco di flag validi è il seguente. I bit inutilizzati sono riservati.
| Valore | Significato |
|---|---|
|
Un utente ha modificato uno o più attributi di file o directory (ad esempio l'attributo di sola lettura, nascosto, di sistema, archivio o sparse) o uno o più timestamp. |
|
Il file o la directory è chiuso. |
|
Lo stato di compressione del file o della directory viene modificato da o in compresso. |
|
Il file o la directory viene aggiunta a . |
|
I dati nel file o nella directory vengono sovrascritti. |
|
Il file o la directory viene troncata. |
|
L'utente apporta una modifica agli attributi estesi del file o della directory. Questi attributi del file system NTFS non sono accessibili alle applicazioni basate su Windows. |
|
Il file o la directory è crittografato o decrittografato. |
|
Il file o la directory viene creato per la prima volta. |
|
Il file o la directory viene eliminato. |
|
Un collegamento rigido del file system NTFS viene aggiunto o rimosso dal file o dalla directory. Un collegamento rigido del file system NTFS, simile a un collegamento rigido POSIX, è una delle diverse voci di directory che visualizzano lo stesso file o directory. |
|
Un utente ha modificato l'attributo FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Ovvero, l'utente ha modificato il file o la directory da uno che può essere indicizzato a uno che non può o viceversa. L'indicizzazione del contenuto consente la ricerca rapida dei dati creando un database di contenuto selezionato. |
|
Sono stati aggiunti uno o più flussi di dati denominati per il file. |
|
I dati in uno o più flussi di dati denominati per il file vengono sovrascritti. |
|
Uno o più flussi di dati denominati per il file vengono troncati. |
|
L'identificatore dell'oggetto del file o della directory viene modificato. |
|
Il file o la directory viene rinominato e il nome del file nella struttura USN_RECORD_V2 o USN_RECORD_V3 che contiene questo record journal è il nuovo nome. |
|
Il file o la directory viene rinominato e il nome del file nella struttura USN_RECORD_V2 o USN_RECORD_V3 che contiene questo record journal è il nome precedente. |
|
Il reparse point contenuto nel file o nella directory viene modificato oppure viene aggiunto o eliminato un punto di ripristino dal file o dalla directory. |
|
Viene apportata una modifica nelle autorizzazioni di accesso al file o alla directory. |
|
Un flusso denominato viene aggiunto o rimosso dal file o dalla directory oppure viene rinominato un flusso denominato. |
ReturnOnlyOnClose
Valore che specifica quando restituire i record del journal delle modifiche.
Per ricevere una notifica quando l'handle finale per il file o la directory modificata viene chiuso, anziché quando si verifica una modifica, impostare ReturnOnlyOnClose su qualsiasi valore diverso da zero e specificare il flag USN_REASON_CLOSE nel membro ReasonMask .
Tutte le modifiche indicate dai flag ReasonMask generano infine una chiamata al software change journal quando il file viene chiuso. Se la chiamata a DeviceIoControl è in attesa della chiusura del file, tale chiamata a sua volta consentirà la restituzione della chiamata a DeviceIoControl . Nel caso in cui un file o una directory non venga chiuso prima di un errore del volume, un errore del sistema operativo o un arresto, viene eseguita una chiamata di pulizia al software del journal delle modifiche al successivo montaggio del volume. La chiamata viene eseguita anche se si verifica un riavvio del sistema in caso di riavvio del sistema.
Per ricevere la notifica la prima volta che ogni modifica viene registrata, nonché in fase di pulizia, impostare ReturnOnlyOnClose su zero.
Indipendentemente dal fatto che ReturnOnlyOnClose sia zero o diverso da zero, i record generati nel log di pulizia all'interno del journal delle modifiche sono tutti i motivi delle modifiche USN apportate al file o alla directory. Ogni volta che si verifica un'operazione di chiusura finale per un elemento, un record di chiusura USN viene scritto nel journal delle modifiche e i flag ReasonMask per l'elemento vengono tutti reimpostati.
Per un file o una directory per cui non esistono dati utente (ad esempio una cartella montata), l'operazione di chiusura finale si verifica quando la funzione CloseHandle viene chiamata sull'ultimo handle utente all'elemento.
Timeout
Il valore di timeout, in secondi, usato con il membro BytesToWaitFor per indicare al sistema operativo cosa fare se l'operazione di FSCTL_READ_USN_JOURNAL richiede più dati che esistano nel journal delle modifiche.
Se timeout è zero e ByteToWaitFor non è zero e la chiamata all'operazione di FSCTL_READ_USN_JOURNAL raggiunge la fine del journal di modifica senza trovare i dati da restituire, FSCTL_READ_USN_JOURNAL attendere fino a quando non sono stati aggiunti byte di dati non filtrati al journal di modifica e quindi recupera i record specificati.
Se timeout è diverso da zero e BytesToWaitFor non è zero e la chiamata all'operazione di FSCTL_READ_USN_JOURNAL raggiunge la fine del journal di modifica senza trovare i dati da restituire, FSCTL_READ_USN_JOURNAL attende i secondi di timeout e quindi tenta di restituire i record specificati. Dopo i secondi di timeout , FSCTL_READ_USN_JOURNAL recupera tutti i record disponibili all'interno dell'intervallo specificato.
In entrambi i casi, dopo il periodo di timeout tutti i nuovi dati aggiunti al journal di modifica vengono elaborati. Se non sono ancora presenti record da restituire dal set specificato, il periodo di timeout viene ripetuto. In questa modalità , FSCTL_READ_USN_JOURNAL rimane in sospeso finché non viene restituito almeno un record o l'I/O viene annullato.
Se BytesToWaitFor è zero, timeout viene ignorato. Il timeout viene ignorato anche per gli handle aperti in modo asincrono.
BytesToWaitFor
Numero di byte di dati non filtrati aggiunti al journal di modifica. Usare questo valore con Timeout per indicare al sistema operativo cosa fare se l'operazione di FSCTL_READ_USN_JOURNAL richiede più dati di quanto esista nel journal delle modifiche.
Se BytesToWaitFor è zero, timeout viene ignorato. In questo caso, l'operazione di FSCTL_READ_USN_JOURNAL restituisce sempre correttamente quando viene rilevata la fine del file del journal di modifica. Recupera anche l'USN che deve essere usato per l'operazione di FSCTL_READ_USN_JOURNAL successiva. Quando l'USN successivo restituito è uguale a StartUsn fornito, non sono disponibili record. Il processo di chiamata non deve usare nuovamente FSCTL_READ_USN_JOURNAL immediatamente.
Poiché la quantità di dati restituiti non può essere stimata quando BytesToWaitFor è zero, si verifica un rischio di overflow del buffer di output. Per ridurre questo rischio, specificare un valore nonzero BytesToWaitFor in operazioni ripetute FSCTL_READ_USN_JOURNAL fino a quando non vengono esauriti tutti i record nel journal delle modifiche. Specificare quindi zero per attendere nuovi record.
In alternativa, usare il parametro lpBytesReturned di DeviceIoControl nella chiamata all'operazione di FSCTL_READ_USN_JOURNAL per determinare la quantità di dati disponibili, riallocare il buffer di output (con spazio da risparmiare per i nuovi record) e chiamare di nuovo DeviceIoControl .
UsnJournalID
Identificatore dell'istanza del journal corrente per il volume.
Il file system NTFS può perdere l'inserimento di eventi nel journal delle modifiche se il journal di modifiche viene arrestato e riavviato o eliminato e ricreato. Se si verifica uno di questi eventi, il file system NTFS fornisce al journal un nuovo identificatore. Se l'identificatore del journal non accetta l'identificatore del journal corrente, la chiamata a DeviceIoControl ha esito negativo e restituisce un codice di errore appropriato. Per recuperare il nuovo identificatore del journal, chiamare DeviceIoControl con l'operazione di FSCTL_QUERY_USN_JOURNAL .
Requisiti
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Intestazione | winioctl.h (include Windows.h) |