Condividi tramite


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
USN_REASON_BASIC_INFO_CHANGE
0x00008000
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.
USN_REASON_CLOSE
0x80000000
Il file o la directory è chiuso.
USN_REASON_COMPRESSION_CHANGE
0x00020000
Lo stato di compressione del file o della directory viene modificato da o in compresso.
USN_REASON_DATA_EXTEND
0x00000002
Il file o la directory viene aggiunta a .
USN_REASON_DATA_OVERWRITE
0x00000001
I dati nel file o nella directory vengono sovrascritti.
USN_REASON_DATA_TRUNCATION
0x00000004
Il file o la directory viene troncata.
USN_REASON_EA_CHANGE
0x00000400
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.
USN_REASON_ENCRYPTION_CHANGE
0x00040000
Il file o la directory è crittografato o decrittografato.
USN_REASON_FILE_CREATE
0x00000100
Il file o la directory viene creato per la prima volta.
USN_REASON_FILE_DELETE
0x00000200
Il file o la directory viene eliminato.
USN_REASON_HARD_LINK_CHANGE
0x00010000
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.
USN_REASON_INDEXABLE_CHANGE
0x00004000
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.
USN_REASON_NAMED_DATA_EXTEND
0x00000020
Sono stati aggiunti uno o più flussi di dati denominati per il file.
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
I dati in uno o più flussi di dati denominati per il file vengono sovrascritti.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
Uno o più flussi di dati denominati per il file vengono troncati.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
L'identificatore dell'oggetto del file o della directory viene modificato.
USN_REASON_RENAME_NEW_NAME
0x00002000
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.
USN_REASON_RENAME_OLD_NAME
0x00001000
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.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
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.
USN_REASON_SECURITY_CHANGE
0x00000800
Viene apportata una modifica nelle autorizzazioni di accesso al file o alla directory.
USN_REASON_STREAM_CHANGE
0x00200000
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)

Vedi anche

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD