struttura USN_RECORD_V4 (winioctl.h)

Articolo
03/04/2024

Contiene le informazioni per un record del journal di modifica usn (Update Sequence Number) versione 4.0. I record della versione 2.0 e 3.0 sono definiti rispettivamente dalle strutture USN_RECORD_V2 (dette anche USN_RECORD) e USN_RECORD_V3 .

Sintassi

typedef struct {
  USN_RECORD_COMMON_HEADER Header;
  FILE_ID_128              FileReferenceNumber;
  FILE_ID_128              ParentFileReferenceNumber;
  USN                      Usn;
  DWORD                    Reason;
  DWORD                    SourceInfo;
  DWORD                    RemainingExtents;
  WORD                     NumberOfExtents;
  WORD                     ExtentSize;
  USN_RECORD_EXTENT        Extents[1];
} USN_RECORD_V4, *PUSN_RECORD_V4;

Members

Header

Struttura USN_RECORD_COMMON_HEADER che descrive la lunghezza del record, la versione principale e la versione secondaria per il record.

FileReferenceNumber

Numero ordinale a 128 bit del file o della directory per cui viene modificato questo record.

Questo valore è un valore assegnato arbitrariamente che associa un record journal a un file.

ParentFileReferenceNumber

Numero ordinale a 128 bit della directory in cui si trova il file o la directory associata a questo record.

Questo valore è un valore assegnato arbitrariamente che associa un record journal a una directory padre.

Usn

USN di questo record.

Reason

Flag che identificano i motivi delle modifiche accumulate in questo file o record del journal di directory dall'apertura del file o della directory.

Quando un file o una directory viene chiuso, viene generato un record USN finale con il flag USN_REASON_CLOSE impostato. La modifica successiva, ad esempio dopo l'operazione di apertura o l'eliminazione successiva, avvia un nuovo record con un nuovo set di flag motivo.

Un'operazione di ridenominazione o spostamento genera due record USN, uno che registra la directory padre precedente per l'elemento e uno che registra un nuovo elemento padre.

Nella tabella seguente vengono identificati i flag possibili.

Nota 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, attributo di sola lettura, nascosto, 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 estesa (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 ha apportato una modifica agli attributi estesi di un file o di una 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 modifica l'attributo FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Ovvero, l'utente modifica il file o la directory da uno in cui il contenuto può essere indicizzato in uno in cui il contenuto non può essere indicizzato o viceversa. L'indicizzazione del contenuto consente la ricerca rapida dei dati creando un database di contenuto selezionato.
USN_REASON_INTEGRITY_CHANGE 0x00800000	Un utente ha modificato lo stato dell'attributo FILE_ATTRIBUTE_INTEGRITY_STREAM per il flusso specificato. Nel file system ReFS i flussi di integrità mantengono un checksum di tutti i dati per tale flusso, in modo che il contenuto del file possa essere convalidato durante le operazioni di lettura o scrittura.
USN_REASON_NAMED_DATA_EXTEND 0x00000020	Uno o più flussi di dati denominati per un file vengono estesi (aggiunti a).
USN_REASON_NAMED_DATA_OVERWRITE 0x00000010	I dati in uno o più flussi di dati denominati per un file vengono sovrascritti.
USN_REASON_NAMED_DATA_TRUNCATION 0x00000040	Uno o più flussi di dati denominati per un file vengono troncati.
USN_REASON_OBJECT_ID_CHANGE 0x00080000	L'identificatore dell'oggetto di un file o di una directory viene modificato.
USN_REASON_RENAME_NEW_NAME 0x00002000	Viene rinominato un file o una directory e il nome del file nella struttura USN_RECORD_V4 è il nuovo nome.
USN_REASON_RENAME_OLD_NAME 0x00001000	Il file o la directory viene rinominata e il nome del file nella struttura USN_RECORD_V4 è il nome precedente.
USN_REASON_REPARSE_POINT_CHANGE 0x00100000	Il reparse point contenuto in un file o in una directory viene modificato oppure viene aggiunto o eliminato da un file o da una directory.
USN_REASON_SECURITY_CHANGE 0x00000800	Viene apportata una modifica nei diritti di accesso a un file o a una directory.
USN_REASON_STREAM_CHANGE 0x00200000	Un flusso denominato viene aggiunto o rimosso da un file oppure viene rinominato un flusso denominato.
USN_REASON_TRANSACTED_CHANGE 0x00400000	Il flusso specificato viene modificato tramite una transazione TxF di cui è stato eseguito il commit.

SourceInfo

Informazioni aggiuntive sull'origine della modifica, impostate dal FSCTL_MARK_HANDLE dell'operazione DeviceIoControl .

Quando un thread scrive un nuovo record USN, i flag di informazioni di origine nel record precedente continuano a essere presenti solo se il thread imposta anche tali flag. Pertanto, la struttura delle informazioni di origine consente alle applicazioni di filtrare i record USN impostati solo da un'origine nota, ad esempio un filtro antivirus.

È possibile impostare uno dei valori seguenti.

Valore	Significato
USN_SOURCE_AUXILIARY_DATA 0x00000002	L'operazione aggiunge un flusso di dati privato a un file o a una directory. Un esempio è un rilevatore di virus che aggiunge informazioni di checksum. Quando il rilevatore di virus modifica l'elemento, il sistema genera record USN. USN_SOURCE_AUXILIARY_DATA indica che le modifiche non hanno modificato i dati dell'applicazione.
USN_SOURCE_DATA_MANAGEMENT 0x00000001	L'operazione fornisce informazioni su una modifica al file o alla directory apportata dal sistema operativo. Un uso tipico è quando il sistema di archiviazione remota sposta i dati da una risorsa di archiviazione esterna a quella locale. Archiviazione remota è il software di gestione dell'archiviazione gerarchico. Tale spostamento in genere aggiunge almeno il flag USN_REASON_DATA_OVERWRITE a un record USN. Tuttavia, i dati non sono cambiati dal punto di vista dell'utente. Notando USN_SOURCE_DATA_MANAGEMENT nel membro SourceInfo , è possibile determinare che, anche se viene eseguita un'operazione di scrittura sull'elemento, i dati non sono stati modificati.
USN_SOURCE_REPLICATION_MANAGEMENT 0x00000004	L'operazione sta modificando un file in modo che corrisponda al contenuto dello stesso file presente in un altro membro del set di repliche.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT 0x00000008	L'operazione sta modificando un file nei sistemi client in modo che corrisponda al contenuto dello stesso file presente nel cloud.

RemainingExtents

Numero di extent che rimangono dopo il record di USN_RECORD_V4 corrente. Per descrivere tutti gli extent modificati per un determinato file, possono essere necessari più record versione 4.0. Quando il membro RemainingExtents è 0, il record USN_RECORD_V4 corrente è l'ultimo record USN_RECORD_V4 per il file. L'ultima voce USN_RECORD_V4 per un determinato file è sempre seguita da un record USN_RECORD_V3 con almeno il flag USN_REASON_CLOSE impostato.

NumberOfExtents

Numero di extent nella voce di USN_RECORD_V4 corrente.

ExtentSize

Dimensione di ogni struttura USN_RECORD_EXTENT nel membro Extents , in byte.

Extents[1]

Matrice di strutture USN_RECORD_EXTENT che rappresentano gli extent nella voce USN_RECORD_V4 .

Commenti

Un record USN_RECORD_V4 viene restituito solo quando viene attivato il rilevamento dell'intervallo e le dimensioni del file sono uguali o maggiori del valore del membro RangeTrackFileSizeThreshold . L'utente riceve sempre uno o più record USN_RECORD_V4 seguiti da un record USN_RECORD_V3 .

Per garantire una compatibilità di avanzamento del percorso nei client del journal delle modifiche, Microsoft fornisce un numero di versione principale e secondario del software change journal nella struttura USN_RECORD_V4 . Il codice deve esaminare questi valori, esaminare la propria compatibilità con il software change journal e gestire normalmente eventuali incompatibilità, se necessario.

Una modifica nel numero di versione secondaria indica che i membri della struttura USN_RECORD_V4 esistenti sono ancora validi, ma che i nuovi membri potrebbero essere stati aggiunti tra il penultimo membro e l'ultimo, ovvero una stringa a lunghezza variabile.

Per gestire questa modifica normalmente, il codice non deve eseguire alcuna aritmetica del puntatore in fase di compilazione che si basa sulla posizione dell'ultimo membro. Ad esempio, una modifica nel numero di versione secondaria rende la sizeof(USN_RECORD) chiamata inaffidabile. Si basano invece sui calcoli in fase di esecuzione che usano il membro RecordLength .

Un aumento del numero di versione principale del software del journal delle modifiche indica che la struttura USN_RECORD_V4 potrebbe aver subito modifiche importanti e che la definizione corrente potrebbe non essere affidabile. Se il codice rileva una modifica nel numero di versione principale del software change journal, il codice non deve funzionare con il journal delle modifiche.

Per altre informazioni, vedere Creazione, modifica ed eliminazione di una modifica Journal.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1 [solo app desktop]
Server minimo supportato	Windows Server 2012 R2 [solo app desktop]
Intestazione	winioctl.h (include Windows.h)