structure USN_RECORD_V4 (winioctl.h)

Article
03/08/2023

Contient les informations d’un enregistrement de journal de modifications du nombre de séquences de mise à jour (USN) version 4.0. Les enregistrements versions 2.0 et 3.0 sont respectivement définis par les structures USN_RECORD_V2 (également appelée USN_RECORD) et USN_RECORD_V3.

Syntaxe

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;

Membres

Header

Une structure USN_RECORD_COMMON_HEADER qui décrit la longueur de l’enregistrement, la version principale et la version mineure de l’enregistrement.

FileReferenceNumber

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

Cette valeur est 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.

Cette valeur est une valeur attribuée arbitrairement qui associe un enregistrement de journal à un répertoire parent.

Usn

USN de cet enregistrement.

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. Ces attributs de système de fichiers NTFS ne sont pas accessibles aux applications Windows.
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_V4 est le nouveau nom.
USN_REASON_RENAME_OLD_NAME 0x00001000	Le fichier ou le répertoire est renommé, et le nom du fichier dans la structure USN_RECORD_V4 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é via une transaction TxF validée.

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 d’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 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 ajoutant 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.

RemainingExtents

Nombre d’extensions qui restent après l’enregistrement USN_RECORD_V4 actuel. Plusieurs enregistrements de version 4.0 peuvent être nécessaires pour décrire toutes les extensions modifiées pour un fichier donné. Lorsque le membre RemainingExtents est 0, l’enregistrement USN_RECORD_V4 actuel est le dernier enregistrement USN_RECORD_V4 du fichier. La dernière entrée USN_RECORD_V4 pour un fichier donné est toujours suivie d’un enregistrement USN_RECORD_V3 avec au moins l’indicateur USN_REASON_CLOSE défini.

NumberOfExtents

Nombre d’étendues dans l’entrée USN_RECORD_V4 actuelle.

ExtentSize

Taille de chaque structure USN_RECORD_EXTENT dans le membre Extents, en octets .

Extents[1]

Tableau de structures USN_RECORD_EXTENT qui représentent les étendues dans l’entrée USN_RECORD_V4 .

Remarques

Un enregistrement USN_RECORD_V4 n’est généré que lorsque le suivi de plage est activé et que la taille de fichier est égale ou supérieure à la valeur du membre RangeTrackFileSizeThreshold . L’utilisateur reçoit toujours un ou plusieurs enregistrements USN_RECORD_V4 suivis d’un enregistrement USN_RECORD_V3 .

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

Une modification du numéro de version secondaire indique que les membres de structure USN_RECORD_V4 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, une modification du numéro de version mineure rend l’appel sizeof(USN_RECORD) non fiable. Au lieu de cela, utilisez des calculs d’exécution qui utilisent le membre RecordLength .

Une augmentation du numéro de version principale du logiciel de journal des modifications indique que la structure USN_RECORD_V4 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 du journal des modifications, le code 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.1 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 R2 [applications de bureau uniquement]
En-tête	winioctl.h (inclure Windows.h)