Partager via


structure USN_RECORD_V3 (winioctl.h)

Contient les informations d’un enregistrement de journal de modifications du nombre de séquences de mise à jour (USN) version 3.0. L’enregistrement version 2.0 est défini par la structure USN_RECORD_V2 (également appelée structure USN_RECORD ).

Syntaxe

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;

Membres

RecordLength

Longueur totale d’un enregistrement, en octets.

Étant donné que USN_RECORD_V3 est d’une taille variable, le membre RecordLength doit être utilisé lors du calcul de l’adresse de l’enregistrement suivant dans une mémoire tampon de sortie, par exemple, une mémoire tampon retournée à partir d’opérations pour la fonction DeviceIoControl qui fonctionne avec USN_RECORD_V3.

La taille en octets de tout enregistrement de journal des modifications correspond au plus à la taille de la structure USN_RECORD_V3 , plus les caractères MaximumComponentLength moins 1 (pour le caractère déclaré dans la structure) fois la taille d’un caractère large. La valeur de MaximumComponentLength peut être déterminée en appelant le
Fonction GetVolumeInformation . Dans C, vous pouvez déterminer une taille d’enregistrement à l’aide de l’exemple de code suivant.

C++
  MaximumChangeJournalRecordSize = 
      QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR) 
       + sizeof(USN_RECORD_V3) );
Pour maintenir la compatibilité entre les modifications de version du logiciel de journal des modifications, utilisez un calcul d’exécution pour déterminer la taille de la structure USN_RECORD_V3 . Pour plus d’informations sur la compatibilité entre les modifications de version, consultez la section Remarques de cette rubrique.

MajorVersion

Numéro de version principale du logiciel de journal des modifications pour cet enregistrement.

Par exemple, si le logiciel de journal des modifications est la version 3.0, le numéro de version principale est 3.

Valeur Signification
2
La structure est une structure USN_RECORD_V2 et le reste de la structure doit être analysé à l’aide de cette disposition.
3
La structure est une structure USN_RECORD_V3 et le reste de la structure doit être analysé à l’aide de cette disposition.
4
La structure est une [structure USN_RECORD_V4](ns-winioctl-usn_record_v4.md) et le reste de la structure doit être analysé à l’aide de cette disposition.

MinorVersion

Numéro de version secondaire du logiciel de journal des modifications pour cet enregistrement. Par exemple, si le logiciel de journal des modifications est la version 3.0, le numéro de version secondaire est égal à zéro.

FileReferenceNumber

Numéro ordinal 128 bits du fichier ou du répertoire pour lequel cet enregistrement note les modifications.

Il s’agit d’une valeur attribuée arbitrairement qui associe un enregistrement de journal à un fichier.

ParentFileReferenceNumber

Numéro ordinal 128 bits du répertoire où se trouve le fichier ou le répertoire associé à cet enregistrement.

Il s’agit d’une valeur attribuée arbitrairement qui associe un enregistrement de journal à un répertoire parent.

Usn

USN de cet enregistrement.

TimeStamp

Horodatage UTC standard (FILETIME) de cet enregistrement, au format 64 bits.

Reason

Indicateurs qui identifient les raisons des modifications qui se sont accumulées dans cet enregistrement de journal de fichiers ou de répertoires depuis l’ouverture du fichier ou du répertoire.

Lorsqu’un fichier ou un répertoire se ferme, un enregistrement USN final est généré avec l’indicateur USN_REASON_CLOSE défini. La modification suivante (par exemple, après l’opération d’ouverture ou de suppression suivante) démarre un nouvel enregistrement avec un nouvel ensemble d’indicateurs de raison.

Une opération de renommage ou de déplacement génère deux enregistrements USN, l’un qui enregistre l’ancien répertoire parent de l’élément et l’autre qui enregistre un nouveau parent.

Le tableau suivant identifie les indicateurs possibles.

Note Les bits inutilisés sont réservés.
 
Valeur Signification
USN_REASON_BASIC_INFO_CHANGE
0x00008000
Un utilisateur a modifié un ou plusieurs attributs de fichier ou de répertoire (par exemple, l’attribut lecture seule, masqué, système, archive ou éparse), ou un ou plusieurs horodatages.
USN_REASON_CLOSE
0x80000000
Le fichier ou le répertoire est fermé.
USN_REASON_COMPRESSION_CHANGE
0x00020000
L’état de compression du fichier ou du répertoire passe de ou à compressé.
USN_REASON_DATA_EXTEND
0x00000002
Le fichier ou le répertoire est étendu (ajouté à).
USN_REASON_DATA_OVERWRITE
0x00000001
Les données du fichier ou du répertoire sont remplacées.
USN_REASON_DATA_TRUNCATION
0x00000004
Le fichier ou le répertoire est tronqué.
USN_REASON_EA_CHANGE
0x00000400
L’utilisateur a apporté une modification aux attributs étendus d’un fichier ou d’un répertoire.
USN_REASON_ENCRYPTION_CHANGE
0x00040000
Le fichier ou le répertoire est chiffré ou déchiffré.
USN_REASON_FILE_CREATE
0x00000100
Le fichier ou le répertoire est créé pour la première fois.
USN_REASON_FILE_DELETE
0x00000200
Le fichier ou le répertoire est supprimé.
USN_REASON_HARD_LINK_CHANGE
0x00010000
Un lien dur du système de fichiers NTFS est ajouté au fichier ou au répertoire ou supprimé.

Un lien physique de système de fichiers NTFS, similaire à un lien physique POSIX, est l’une des entrées de répertoire qui voient le même fichier ou répertoire.

USN_REASON_INDEXABLE_CHANGE
0x00004000
Un utilisateur modifie l’attribut FILE_ATTRIBUTE_NOT_CONTENT_INDEXED .

Autrement dit, l’utilisateur change le fichier ou le répertoire d’un fichier où le contenu peut être indexé à un autre où le contenu ne peut pas être indexé, ou inversement. L’indexation de contenu permet une recherche rapide des données en créant une base de données de contenu sélectionné.

USN_REASON_INTEGRITY_CHANGE
0x00800000
Un utilisateur a modifié l’état de l’attribut FILE_ATTRIBUTE_INTEGRITY_STREAM pour le flux donné.

Sur le système de fichiers ReFS, les flux d’intégrité conservent une somme de contrôle de toutes les données de ce flux, afin que le contenu du fichier puisse être validé pendant les opérations de lecture ou d’écriture.

USN_REASON_NAMED_DATA_EXTEND
0x00000020
Le ou les flux de données nommés d’un fichier sont étendus (ajoutés à).
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
Les données d’un ou de plusieurs flux de données nommés d’un fichier sont remplacées.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
Le ou plusieurs flux de données nommés d’un fichier sont tronqués.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
L’identificateur d’objet d’un fichier ou d’un répertoire est modifié.
USN_REASON_RENAME_NEW_NAME
0x00002000
Un fichier ou un répertoire est renommé, et le nom de fichier dans la structure USN_RECORD_V3 est le nouveau nom.
USN_REASON_RENAME_OLD_NAME
0x00001000
Le fichier ou le répertoire est renommé, et le nom de fichier dans la structure USN_RECORD_V3 est le nom précédent.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
Le point d’analyse contenu dans un fichier ou un répertoire est modifié, ou un point d’analyse est ajouté ou supprimé d’un fichier ou d’un répertoire.
USN_REASON_SECURITY_CHANGE
0x00000800
Une modification est apportée aux droits d’accès à un fichier ou à un répertoire.
USN_REASON_STREAM_CHANGE
0x00200000
Un flux nommé est ajouté ou supprimé d’un fichier, ou un flux nommé est renommé.
USN_REASON_TRANSACTED_CHANGE
0x00400000
Le flux donné est modifié par le biais d’une transaction TxF.

SourceInfo

Informations supplémentaires sur la source de la modification, définies par le FSCTL_MARK_HANDLE de l’opération DeviceIoControl .

Lorsqu’un thread écrit un nouvel enregistrement USN, les indicateurs d’informations sources dans l’enregistrement précédent continuent d’être présents uniquement si le thread définit également ces indicateurs. Par conséquent, la structure des informations sources permet aux applications de filtrer les enregistrements USN définis uniquement par une source connue, par exemple un filtre antivirus.

L’une des deux valeurs suivantes peut être définie.

Valeur Signification
USN_SOURCE_AUXILIARY_DATA
0x00000002
L’opération ajoute un flux de données privé à un fichier ou un répertoire.

Par exemple, un détecteur de virus peut ajouter des informations de somme de contrôle. Lorsque le détecteur de virus modifie l’élément, le système génère des enregistrements USN. USN_SOURCE_AUXILIARY_DATA indique que les modifications n’ont pas modifié les données de l’application.

USN_SOURCE_DATA_MANAGEMENT
0x00000001
L’opération fournit des informations sur une modification apportée au fichier ou au répertoire par le système d’exploitation.

Une utilisation courante est lorsque le système de stockage à distance déplace des données d’un stockage externe vers un stockage local. Le stockage à distance est le logiciel de gestion du stockage hiérarchique. Un tel déplacement ajoute généralement au minimum l’indicateur USN_REASON_DATA_OVERWRITE à un enregistrement USN. Toutefois, les données n’ont pas changé du point de vue de l’utilisateur. En notant USN_SOURCE_DATA_MANAGEMENT dans le membre SourceInfo , vous pouvez déterminer que même si une opération d’écriture est effectuée sur l’élément, les données n’ont pas changé.

USN_SOURCE_REPLICATION_MANAGEMENT
0x00000004
L’opération modifie un fichier pour qu’il corresponde au contenu du même fichier qui existe dans un autre membre de l’ensemble de réplica.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT
0x00000008
L’opération modifie un fichier sur les systèmes clients pour qu’il corresponde au contenu du même fichier qui existe dans le cloud.

SecurityId

Identificateur de sécurité unique affecté au fichier ou au répertoire associé à cet enregistrement.

FileAttributes

Attributs du fichier ou du répertoire associé à cet enregistrement, tels que retournés par la fonction GetFileAttributes . Les attributs des flux associés au fichier ou au répertoire sont exclus.

FileNameLength

Longueur du nom du fichier ou du répertoire associé à cet enregistrement, en octets. Le membre FileName contient ce nom. Utilisez ce membre pour déterminer la longueur du nom de fichier, plutôt que de dépendre d’un « \0 » de fin pour délimiter le nom de fichier dans FileName.

FileNameOffset

Décalage du membre FileName par rapport au début de la structure.

FileName[1]

Nom du fichier ou du répertoire associé à cet enregistrement au format Unicode. Ce nom de fichier ou de répertoire est de longueur variable.

Lorsque vous utilisez FileName, ne comptez pas sur le nom de fichier qui contient un délimiteur « \0 » de fin, mais déterminez plutôt la longueur du nom de fichier à l’aide de FileNameLength.

N’effectuez pas d’arithmétique de pointeur au moment de la compilation à l’aide de FileName. Au lieu de cela, effectuez les calculs nécessaires au moment de l’exécution en utilisant la valeur du membre FileNameOffset . Cela permet de rendre votre code compatible avec toutes les versions futures de USN_RECORD_V3.

Remarques

Dans les mémoires tampons de sortie retournées par les opérations DeviceIoControl qui fonctionnent avec USN_RECORD_V3, tous les enregistrements sont alignés sur les limites 64 bits à partir du début de la mémoire tampon.

Lorsque le suivi de plage est activé, NTFS bascule vers la production uniquement d’enregistrements USN_RECORD_V3 comme sortie.

Pour fournir un chemin d’accès à la compatibilité vers le haut dans les clients de journal des modifications, Microsoft fournit un numéro de version majeure et secondaire du logiciel de journal des modifications dans la structure USN_RECORD_V3 . Votre code doit examiner ces valeurs, détecter sa propre compatibilité avec le logiciel de journal des modifications et, si nécessaire, gérer correctement toute incompatibilité.

Une modification du numéro de version secondaire indique que les membres de structure USN_RECORD_V3 existants sont toujours valides, mais que de nouveaux membres ont peut-être été ajoutés entre l’avant-dernier membre et le dernier, qui est une chaîne de longueur variable.

Pour gérer correctement une telle modification, votre code ne doit pas effectuer d’arithmétique de pointeur au moment de la compilation qui repose sur l’emplacement du dernier membre. Par exemple, cela rend le code sizeof(USN_RECORD) C non fiable. Au lieu de cela, utilisez les calculs d’exécution à l’aide du membre RecordLength .

Une augmentation du numéro de version principale du logiciel de journal des modifications indique que la structure USN_RECORD_V3 a peut-être subi des modifications majeures et que la définition actuelle peut ne pas être fiable. Si votre code détecte une modification dans le numéro de version principale du logiciel de journal des modifications, il ne doit pas fonctionner avec le journal des modifications.

Pour plus d’informations, consultez Création, modification et suppression d’un Journal de modification.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau uniquement]
En-tête winioctl.h (inclure Windows.h)

Voir aussi

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V2

USN_RECORD_V4 structure

Structures de gestion des volumes