Partager via


structure READ_USN_JOURNAL_DATA_V0 (winioctl.h)

Contient des informations définissant un ensemble d’enregistrements de journal de modification de numéro de séquence de mise à jour (USN) pour revenir au processus d’appel. Il est utilisé par les codes de contrôle FSCTL_QUERY_USN_JOURNAL et FSCTL_READ_USN_JOURNAL . Avant Windows 8 et Windows Server 2012 cette structure était nommée READ_USN_JOURNAL_DATA. Utilisez ce nom pour compiler avec des sdk et des compilateurs plus anciens. Windows Server 2012 introduit READ_USN_JOURNAL_DATA_V1 pour prendre en charge les identificateurs de fichiers 128 bits utilisés par ReFS.

Syntaxe

typedef struct {
  USN       StartUsn;
  DWORD     ReasonMask;
  DWORD     ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;

Membres

StartUsn

USN à laquelle commencer la lecture du journal des modifications.

Pour démarrer l’opération de lecture au premier enregistrement du journal, définissez le membre StartUsn sur zéro. Étant donné qu’un USN est contenu dans chaque enregistrement de journal, la mémoire tampon de sortie indique à quel enregistrement l’opération de lecture a réellement démarré.

Pour démarrer l’opération de lecture à un enregistrement spécifique, définissez StartUsn sur cet enregistrement USN.

Si un USN différent de zéro est spécifié qui est inférieur au premier USN dans le journal des modifications, une erreur se produit et le code d’erreur ERROR_JOURNAL_ENTRY_DELETED est retourné. Ce code peut indiquer un cas dans lequel l’USN spécifié est valide à un moment donné, mais a été supprimé depuis.

Pour plus d’informations sur la navigation dans la mémoire tampon du journal des modifications retournée dans READ_USN_JOURNAL_DATA_V0, consultez Parcourir une mémoire tampon des enregistrements du journal des modifications.

ReasonMask

Masque d’indicateurs, chaque indicateur notant une modification pour laquelle le fichier ou le répertoire a un enregistrement dans le journal des modifications. Pour être retourné dans une opération de FSCTL_READ_USN_JOURNAL , un enregistrement de journal des modifications doit avoir au moins l’un de ces indicateurs défini.

La liste des indicateurs valides est la suivante. 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 (tels que 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 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 apporte une modification aux attributs étendus du fichier ou du 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 a modifié l’attribut FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Autrement dit, l’utilisateur a modifié le fichier ou le répertoire d’un fichier qui peut être indexé à un fichier qui 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 du contenu sélectionné.)
USN_REASON_NAMED_DATA_EXTEND
0x00000020
Un ou plusieurs flux de données nommés pour le fichier ont été ajoutés à.
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
Les données d’un ou de plusieurs flux de données nommés pour le fichier sont remplacées.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
Un ou plusieurs flux de données nommés pour le fichier sont tronqués.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
L’identificateur d’objet du fichier ou du répertoire est modifié.
USN_REASON_RENAME_NEW_NAME
0x00002000
Le fichier ou le répertoire est renommé, et le nom du fichier dans la structure USN_RECORD_V2 ou USN_RECORD_V3 qui contient cet enregistrement de journal 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_V2 ou USN_RECORD_V3 qui contient cet enregistrement de journal est le nom précédent.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
Le point d’analyse contenu dans le fichier ou le répertoire est modifié, ou un point d’analyse est ajouté ou supprimé du fichier ou du répertoire.
USN_REASON_SECURITY_CHANGE
0x00000800
Une modification est apportée aux autorisations d’accès au fichier ou au répertoire.
USN_REASON_STREAM_CHANGE
0x00200000
Un flux nommé est ajouté ou supprimé du fichier ou du répertoire, ou un flux nommé est renommé.

ReturnOnlyOnClose

Valeur qui spécifie quand retourner les enregistrements du journal des modifications.

Pour recevoir une notification lorsque le handle final du fichier ou du répertoire modifié est fermé, plutôt qu’au moment où une modification se produit, définissez ReturnOnlyOnClose sur une valeur différente de zéro et spécifiez l’indicateur USN_REASON_CLOSE dans le membre ReasonMask .

Toutes les modifications indiquées par les indicateurs ReasonMask génèrent finalement un appel au logiciel de journal des modifications lorsque le fichier est fermé. Si votre appel DeviceIoControl attend la fermeture du fichier, cet appel à son tour permettra à votre appel DeviceIoControl de revenir. Dans le cas où un fichier ou un répertoire n’est pas fermé avant une défaillance de volume, une défaillance du système d’exploitation ou un arrêt, un appel de nettoyage au logiciel de journal des modifications se produit la prochaine fois que le volume est monté. L’appel se produit même si un redémarrage du système intervient.

Pour recevoir une notification la première fois que chaque modification est journalisée, ainsi que lors du nettoyage, définissez ReturnOnlyOnClose sur zéro.

Que ReturnOnlyOnClose soit égal à zéro ou à zéro, les enregistrements générés dans le journal de nettoyage dans le journal des modifications ont toutes les raisons des modifications USN qui se sont produites dans le fichier ou le répertoire. Chaque fois qu’une opération de fermeture finale se produit pour un élément, un enregistrement de fermeture USN est écrit dans le journal des modifications, et les indicateurs ReasonMask de l’élément sont tous réinitialisés.

Pour un fichier ou un répertoire pour lequel il n’existe aucune donnée utilisateur (par exemple, un dossier monté), l’opération de fermeture finale se produit lorsque la fonction CloseHandle est appelée sur le dernier handle utilisateur de l’élément.

Timeout

Valeur du délai d’attente, en secondes, utilisée avec le membre BytesToWaitFor pour indiquer au système d’exploitation ce qu’il faut faire si l’opération FSCTL_READ_USN_JOURNAL demande plus de données qu’il n’en existe dans le journal des modifications.

Si timeout est égal à zéro et que BytesToWaitFor est différent de zéro, et que l’appel d’opération FSCTL_READ_USN_JOURNAL atteint la fin du journal des modifications sans trouver de données à retourner, FSCTL_READ_USN_JOURNAL attend que BytesToWaitFor octets de données non filtrées aient été ajoutés au journal des modifications, puis récupère les enregistrements spécifiés.

Si Timeout est différent de zéro et que BytesToWaitFor est différent de zéro, et que l’appel d’opération FSCTL_READ_USN_JOURNAL atteint la fin du journal des modifications sans trouver de données à retourner, FSCTL_READ_USN_JOURNAL attend timeout secondes, puis tente de retourner les enregistrements spécifiés. Après les secondes de délai d’expiration , FSCTL_READ_USN_JOURNAL récupère tous les enregistrements disponibles dans la plage spécifiée.

Dans les deux cas, après le délai d’attente, toutes les nouvelles données ajoutées au journal des modifications sont traitées. S’il n’y a toujours aucun enregistrement à retourner à partir du jeu spécifié, le délai d’attente est répété. Dans ce mode, FSCTL_READ_USN_JOURNAL reste en attente jusqu’à ce qu’au moins un enregistrement soit retourné ou que les E/S soient annulées.

Si BytesToWaitFor est égal à zéro, le délai d’expiration est ignoré. Le délai d’expiration est également ignoré pour les handles ouverts de manière asynchrone.

BytesToWaitFor

Nombre d’octets de données non filtrées ajoutées au journal des modifications. Utilisez cette valeur avec Timeout pour indiquer au système d’exploitation quoi faire si l’opération FSCTL_READ_USN_JOURNAL demande plus de données qu’il n’en existe dans le journal des modifications.

Si BytesToWaitFor est égal à zéro, le délai d’expiration est ignoré. Dans ce cas, l’opération FSCTL_READ_USN_JOURNAL retourne toujours avec succès lorsque la fin du fichier journal des modifications est rencontrée. Il récupère également l’USN qui doit être utilisé pour la prochaine opération FSCTL_READ_USN_JOURNAL . Lorsque l’USN suivant retourné est identique à celui fourni par StartUsn , aucun enregistrement n’est disponible. Le processus appelant ne doit pas utiliser FSCTL_READ_USN_JOURNAL de nouveau immédiatement.

Étant donné que la quantité de données retournées ne peut pas être prédite lorsque BytesToWaitFor est égal à zéro, vous courez un risque de dépassement de la mémoire tampon de sortie. Pour réduire ce risque, spécifiez une valeur BytesToWaitFor différente de zéro dans les opérations de FSCTL_READ_USN_JOURNAL répétées jusqu’à ce que tous les enregistrements du journal des modifications soient épuisés. Spécifiez ensuite zéro pour attendre les nouveaux enregistrements.

Vous pouvez également utiliser le paramètre lpBytesReturned de DeviceIoControl dans l’appel d’opération FSCTL_READ_USN_JOURNAL pour déterminer la quantité de données disponibles, réallouer la mémoire tampon de sortie (avec de la place pour les nouveaux enregistrements) et appeler à nouveau DeviceIoControl .

UsnJournalID

Identificateur de l’instance du journal qui est à jour pour le volume.

Le système de fichiers NTFS peut manquer de placer des événements dans le journal des modifications si le journal des modifications est arrêté et redémarré ou supprimé et recréé. Si l’un de ces événements se produit, le système de fichiers NTFS donne au journal un nouvel identificateur. Si l’identificateur de journal n’est pas en accord avec l’identificateur de journal actuel, l’appel à DeviceIoControl échoue et retourne un code d’erreur approprié. Pour récupérer le nouvel identificateur de journal, appelez DeviceIoControl avec l’opération FSCTL_QUERY_USN_JOURNAL .

Configuration requise

   
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
En-tête winioctl.h (inclure Windows.h)

Voir aussi

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD