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) );
|
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 |
|---|---|
|
La structure est une structure USN_RECORD_V2 et le reste de la structure doit être analysé à l’aide de cette disposition. |
|
La structure est une structure USN_RECORD_V3 et le reste de la structure doit être analysé à l’aide de cette disposition. |
|
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.
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.
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) |