READ_USN_JOURNAL_DATA_V1 struttura (winioctl.h)
Contiene informazioni che definiscono un set di record della sequenza di aggiornamento (USN) per tornare al processo chiamante. Viene usato 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 tale nome per compilare gli SDK e i 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;
WORD MinMajorVersion;
WORD MaxMajorVersion;
} READ_USN_JOURNAL_DATA_V1, *PREAD_USN_JOURNAL_DATA_V1;
Members
StartUsn
USN in corrispondenza del quale iniziare a leggere il giornale di modifica.
Per avviare l'operazione di lettura al primo record del journal, impostare il membro StartUsn su zero. Poiché un USN è contenuto in ogni record del journal, il buffer di output indica in quale record viene effettivamente avviata l'operazione di lettura.
Per avviare l'operazione di lettura in un record specifico, impostare StartUsn su tale record USN.
Se viene specificato un USN diverso da zero che è minore del primo USN nel journal di modifica, 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 alla volta, ma è stato eliminato.
Per altre informazioni sull'esplorazione del buffer del journal di modifica restituito in READ_USN_JOURNAL_DATA_V0, vedere Passaggio di un buffer di modifiche Journal record.
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 di modifica 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 read-only, hidden, system, archive o sparse, o uno o più timestamp. |
|
Il file o la directory viene chiusa. |
|
Lo stato di compressione del file o della directory viene modificato da o in compresso. |
|
Il file o la directory viene aggiunto 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 vengono crittografati o decrittografati. |
|
Il file o la directory viene creato per la prima volta. |
|
Il file o la directory vengono eliminati. |
|
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 una rapida ricerca dei dati creando un database di contenuto selezionato. |
|
Uno o più flussi di dati denominati per il file sono stati aggiunti. |
|
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 di 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 di journal è il nome precedente. |
|
Il punto di riparse contenuto nel file o nella directory viene modificato o viene aggiunto un punto di ripristino o eliminato 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 di modifica.
Per ricevere una notifica quando l'handle finale per il file o la directory modificata viene chiuso, anziché al momento in cui 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 del journal di modifica quando il file viene chiuso. Se la chiamata DeviceIoControl è in attesa della chiusura del file, tale chiamata a sua volta consentirà la restituzione della chiamata DeviceIoControl . Nel caso in cui un file o una directory non venga chiusa prima di un errore del volume, un errore del sistema operativo o un arresto, si verifica una chiamata di pulizia al software del journal di modifica la prossima volta che il volume viene montato. La chiamata si verifica anche se è presente un riavvio del sistema di intervento.
Per ricevere una notifica la prima volta che ogni modifica viene registrata, oltre alla 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 per le modifiche usN che si sono verificate nel file o nella 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 FSCTL_READ_USN_JOURNAL raggiunge la fine del journal di modifica senza trovare i dati da restituire, FSCTL_READ_USN_JOURNAL attende 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 .
MinMajorVersion
MaxMajorVersion
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Intestazione | winioctl.h (include Windows.h) |