USN_RECORD_V2 struttura (winioctl.h)

Articolo
03/09/2024

Contiene le informazioni per un record USN (Update Sequence Number) change journal versione 2.0. Le applicazioni non devono tentare di usare le versioni del journal di modifica precedenti alla versione 2.0. Prima di Windows 8 e Windows Server 2012 questa struttura è stata denominata USN_RECORD. Usare tale nome per compilare gli SDK e i compilatori meno recenti.

Sintassi

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  DWORDLONG     FileReferenceNumber;
  DWORDLONG     ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V2, *PUSN_RECORD_V2;

Members

RecordLength

Lunghezza totale di un record, in byte.

Poiché USN_RECORD_V2 è una dimensione variabile, il membro RecordLength deve essere usato quando si calcola l'indirizzo del record successivo in un buffer di output, ad esempio un buffer restituito dalle operazioni per la funzione DeviceIoControl che funziona con USN_RECORD_V2.

Le dimensioni in byte di qualsiasi record del journal di modifica sono alla maggior parte delle dimensioni della struttura USN_RECORD_V2 , più i caratteri MaximumComponentLength meno 1 (per il carattere dichiarato nella struttura) volte le dimensioni di un carattere wide. Il valore di MaximumComponentLength può essere determinato chiamando l'oggetto
Funzione GetVolumeInformation. In C è possibile determinare una dimensione del record usando l'esempio di codice seguente.

C++
MaximumChangeJournalRecordSize = ( MaximumComponentLength * sizeof(WCHAR) + sizeof(USN_RECORD) + sizeof(WCHAR) );

Per mantenere la compatibilità tra le modifiche della versione del software change journal, usare un calcolo run-time per determinare le dimensioni della struttura di USN_RECORD_V2 . Per altre informazioni sulla compatibilità tra le modifiche alla versione, vedere la sezione Osservazioni in questo argomento.

MajorVersion

Numero di versione principale del software change journal per questo record.

Ad esempio, se il software change journal è versione 2.0, il numero di versione principale è 2.

Valore	Significato
2	La struttura è una struttura USN_RECORD_V2 e la parte restante della struttura deve essere analizzata usando tale layout.
3	La struttura è una struttura USN_RECORD_V3 e la parte restante della struttura deve essere analizzata usando tale layout.
4	La struttura è una [struttura USN_RECORD_V4](ns-winioctl-usn_record_v4.md) e la parte restante della struttura deve essere analizzata usando tale layout.

MinorVersion

Numero di versione secondaria del software change journal per questo record. Ad esempio, se il software change journal è versione 2.0, il numero di versione secondaria è zero.

FileReferenceNumber

Numero ordinale del file o della directory per cui viene modificata la nota del record.

Si tratta di un valore assegnato arbitrariamente che associa un record di journal a un file.

ParentFileReferenceNumber

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

Si tratta di un valore assegnato arbitrariamente che associa un record di journal a una directory padre.

Usn

USN di questo record.

TimeStamp

Il timestamp UTC standard (FILETIME) di questo record, in formato a 64 bit.

Reason

Flag che identificano i motivi per le modifiche accumulate in questo file o record del journal di directory dopo l'apertura del file o della directory.

Quando un file o una directory si chiude, viene generato un record USN finale con il flag di 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 rinominazione o spostamento genera due record USN, uno che registra la directory padre precedente per l'elemento e uno che registra un nuovo padre.

La tabella seguente identifica 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 l'attributo read-only, hidden, system, archive o sparse o uno o più timestamp.
USN_REASON_CLOSE 0x80000000	Il file o la directory viene chiusa.
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 vengono crittografati o decrittografati.
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 vengono eliminati.
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 a uno in cui il contenuto non può essere indicizzato o viceversa. L'indicizzazione dei contenuti consente una rapida ricerca 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 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_V2 è 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_V2 è 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.

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 due 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 potrebbe essere un rilevatore di virus che aggiunge informazioni sul 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.

SecurityId

Identificatore di sicurezza univoco assegnato al file o alla directory associata a questo record.

FileAttributes

Attributi per il file o la directory associati a questo record, come restituito dalla funzione GetFileAttributes . Gli attributi dei flussi associati al file o alla directory vengono esclusi.

FileNameLength

Lunghezza in byte del nome del file o della directory associata a questo record. Il membro FileName contiene questo nome. Utilizzare questo membro per determinare la lunghezza del nome file, anziché in base a un carattere finale '\0' per delimitare il nome file in FileName.

FileNameOffset

Offset del membro FileName dall'inizio della struttura.

FileName[1]

Nome del file o della directory associata a questo record in formato Unicode. Questo nome di file o directory è di lunghezza variabile.

Quando si usa FileName, non contare sul nome file che contiene un delimitatore finale '\0', ma determinare invece la lunghezza del nome file utilizzando FileNameLength.

Non eseguire alcuna aritmetica del puntatore in fase di compilazione usando FileName. Eseguire invece i calcoli necessari in fase di esecuzione usando il valore del membro FileNameOffset . In questo modo è possibile rendere il codice compatibile con qualsiasi versione futura di USN_RECORD_V2.

Commenti

Nei buffer di output restituiti dalle operazioni DeviceIoControl che funzionano con USN_RECORD_V2, tutti i record vengono allineati ai limiti a 64 bit dall'inizio del buffer.

Per fornire un percorso di compatibilità verso l'alto nei client del journal delle modifiche, Microsoft fornisce un numero di versione principale e secondario del software del journal delle modifiche nella struttura USN_RECORD_V2 . Il codice deve esaminare questi valori, rilevare la propria compatibilità con il software change journal e, se necessario, gestire correttamente eventuali incompatibilità.

Una modifica nel numero di versione secondaria indica che i membri della struttura USN_RECORD_V2 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, questo rende il codice sizeof(USN_RECORD) C inaffidabile. Si basano invece sui calcoli in fase di esecuzione usando il membro RecordLength .

Un aumento del numero di versione principale del software del journal delle modifiche indica che la struttura USN_RECORD_V2 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, non dovrebbe 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 XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Intestazione	winioctl.h (include Windows.h)