Condividi tramite


USN_RECORD_V3 struttura (winioctl.h)

Contiene le informazioni per un record usN (Update Sequence Number) change journal versione 3.0. Il record 2.0 della versione 2.0 è definito dalla struttura USN_RECORD_V2 (chiamata anche struttura USN_RECORD ).

Sintassi

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

Members

RecordLength

Lunghezza totale di un record, in byte.

Poiché USN_RECORD_V3 è 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_V3.

Le dimensioni in byte di qualsiasi record del journal di modifica sono alla maggior parte delle dimensioni della struttura USN_RECORD_V3 , 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 = 
      QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR) 
       + sizeof(USN_RECORD_V3) );
Per mantenere la compatibilità tra le modifiche alla versione del software change journal, usare un calcolo di runtime per determinare le dimensioni della struttura USN_RECORD_V3 . 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 3.0, il numero di versione principale è 3.

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 3.0, il numero di versione secondaria è zero.

FileReferenceNumber

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

Si tratta di un valore assegnato arbitrariamente che associa un record di 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.

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.
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_V3 è 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_V3 è il nome precedente.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
Il punto di correzione contenuto in un file o in una directory viene modificato o viene aggiunto un punto di ripristino 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 a o rimosso da un file o un flusso denominato viene rinominato.
USN_REASON_TRANSACTED_CHANGE
0x00400000
Il flusso specificato viene modificato tramite una transazione TxF.

SourceInfo

Informazioni aggiuntive sull'origine della modifica, impostata 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 aggiungendo 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 apportata al file o alla directory apportata dal sistema operativo.

Un uso tipico è quando il sistema di archiviazione remota sposta i dati dall'esterno all'archiviazione locale. Archiviazione remota è il software di gestione dell'archiviazione gerarchica. Tale spostamento in genere aggiunge almeno il flag di USN_REASON_DATA_OVERWRITE a un record USN. Tuttavia, i dati non sono stati modificati dal punto di vista dell'utente. Notando USN_SOURCE_DATA_MANAGEMENT nel membro SourceInfo , è possibile determinare che, anche se un'operazione di scrittura viene eseguita nell'elemento, i dati non sono stati modificati.

USN_SOURCE_REPLICATION_MANAGEMENT
0x00000004
L'operazione modifica 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 modifica 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 sono esclusi.

FileNameLength

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

FileNameOffset

Offset del membro FileName dall'inizio della struttura.

FileName[1]

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

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

Non eseguire alcun puntatore aritmetico in fase di compilazione usando FileName. Invece, effettuare calcoli necessari in fase di esecuzione usando il valore del membro FileNameOffset . In questo modo è possibile rendere il codice compatibile con tutte le versioni future di USN_RECORD_V3.

Commenti

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

Quando viene attivato il rilevamento dell'intervallo, NTFS passa alla produzione di solo record USN_RECORD_V3 come output.

Per fornire un percorso di compatibilità verso l'alto nei client del journal di modifica, Microsoft fornisce un numero di versione principale e secondario del software change journal nella struttura USN_RECORD_V3 . Il codice deve esaminare questi valori, rilevare la propria compatibilità con il software del journal di modifica e, se necessario, gestire in modo appropriato qualsiasi incompatibilità.

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

Per gestire tale modifica in modo normale, il codice non deve eseguire alcun puntatore in fase di compilazione aritmetica che si basa sulla posizione dell'ultimo membro. Ad esempio, il codice sizeof(USN_RECORD) C non è affidabile. Si basano invece sui calcoli di runtime usando il membro RecordLength .

Un aumento del numero di versione principale del software change journal indica che la struttura USN_RECORD_V3 potrebbe avere 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 deve funzionare con il journal di modifica.

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

Requisiti

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

Vedi anche

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V2

USN_RECORD_V4 struttura

Strutture di gestione dei volumi