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 |
|---|---|
|
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. |
|
Le fichier ou le répertoire est fermé. |
|
L’état de compression du fichier ou du répertoire passe de ou à compressé. |
|
Le fichier ou le répertoire est ajouté à. |
|
Les données du fichier ou du répertoire sont remplacées. |
|
Le fichier ou le répertoire est tronqué. |
|
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. |
|
Le fichier ou le répertoire est chiffré ou déchiffré. |
|
Le fichier ou le répertoire est créé pour la première fois. |
|
Le fichier ou le répertoire est supprimé. |
|
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. |
|
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é.) |
|
Un ou plusieurs flux de données nommés pour le fichier ont été ajoutés à. |
|
Les données d’un ou de plusieurs flux de données nommés pour le fichier sont remplacées. |
|
Un ou plusieurs flux de données nommés pour le fichier sont tronqués. |
|
L’identificateur d’objet du fichier ou du répertoire est modifié. |
|
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. |
|
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. |
|
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. |
|
Une modification est apportée aux autorisations d’accès au fichier ou au répertoire. |
|
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) |