ReadDirectoryChangesExW, fonction (winbase.h)

Article
08/27/2023

Récupère des informations qui décrivent les modifications dans le répertoire spécifié, pouvant inclure des informations étendues si ce type d’informations est spécifié. La fonction ne signale pas les modifications apportées au répertoire spécifié.

Pour suivre les modifications effectuées sur un volume, consultez Journaux des modifications.

Syntaxe

BOOL ReadDirectoryChangesExW(
  [in]                HANDLE                                  hDirectory,
  [out]               LPVOID                                  lpBuffer,
  [in]                DWORD                                   nBufferLength,
  [in]                BOOL                                    bWatchSubtree,
  [in]                DWORD                                   dwNotifyFilter,
  [out, optional]     LPDWORD                                 lpBytesReturned,
  [in, out, optional] LPOVERLAPPED                            lpOverlapped,
  [in, optional]      LPOVERLAPPED_COMPLETION_ROUTINE         lpCompletionRoutine,
  [in]                READ_DIRECTORY_NOTIFY_INFORMATION_CLASS ReadDirectoryNotifyInformationClass
);

Paramètres

[in] hDirectory

Handle vers le répertoire à surveiller. Ce répertoire doit être ouvert avec le droit d’accès FILE_LIST_DIRECTORY , ou un droit d’accès tel que GENERIC_READ qui inclut le droit d’accès FILE_LIST_DIRECTORY .

[out] lpBuffer

Pointeur vers la mémoire tampon mise en forme alignée sur DWORD dans laquelle ReadDirectoryChangesExW doit retourner les résultats de lecture. La structure de cette mémoire tampon est définie par la structure FILE_NOTIFY_EXTENDED_INFORMATION si la valeur du paramètre ReadDirectoryNotifyInformationClass est ReadDirectoryNotifyExtendedInformation, ou par la structure FILE_NOTIFY_INFORMATION si ReadDirectoryNotifyInformationClass est ReadDirectoryNotifyInformation.

Cette mémoire tampon est remplie de manière synchrone ou asynchrone, selon la façon dont le répertoire est ouvert et la valeur donnée au paramètre lpOverlapped . Pour plus d'informations, consultez la section Notes.

[in] nBufferLength

Taille de la mémoire tampon vers laquelle pointe le paramètre lpBuffer , en octets.

[in] bWatchSubtree

Si ce paramètre a la valeur TRUE, la fonction surveille l’arborescence de répertoires enracinée dans le répertoire spécifié. Si ce paramètre a la valeur FALSE, la fonction surveille uniquement le répertoire spécifié par le paramètre hDirectory .

[in] dwNotifyFilter

Critères de filtre que la fonction vérifie pour déterminer si l’opération d’attente est terminée. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Toute modification de nom de fichier dans la sous-arborescence ou le répertoire surveillé génère le renvoi d'une opération d'attente d'une notification de modification. Les modifications incluent le renommage, la création ou la suppression d’un fichier.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Tout changement de nom de répertoire dans le répertoire ou la sous-arborescence surveillé entraîne le retour d’une opération d’attente de notification de modification. Les modifications incluent la création ou la suppression d’un répertoire.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Toute modification d'attribut dans la sous-arborescence ou le répertoire surveillé génère le renvoi d'une opération d'attente d'une notification de modification.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Toute modification de taille de fichier dans la sous-arborescence ou le répertoire surveillé génère le renvoi d'une opération d'attente d'une notification de modification. Le système d'exploitation détecte une modification de taille de fichier uniquement lorsque le fichier est écrit sur le disque. Pour les systèmes d'exploitation qui utilisent la mise en cache étendue, la détection se produit uniquement lorsque le cache est suffisamment vidé.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Toute modification de l'heure de dernière écriture des fichiers dans la sous-arborescence ou le répertoire surveillé génère le renvoi d'une opération d'attente d'une notification de modification. Le système d'exploitation détecte une modification à la dernière écriture uniquement lorsque le fichier est écrit sur le disque. Pour les systèmes d'exploitation qui utilisent la mise en cache étendue, la détection se produit uniquement lorsque le cache est suffisamment vidé.
FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020	Toute modification apportée à l’heure du dernier accès des fichiers dans le répertoire ou la sous-arborescence surveillé entraîne le retour d’une opération d’attente de notification de modification.
FILE_NOTIFY_CHANGE_CREATION 0x00000040	Toute modification apportée à l’heure de création des fichiers dans le répertoire ou la sous-arborescence surveillé entraîne le retour d’une opération d’attente de notification de modification.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Toute modification du descripteur de sécurité dans le répertoire ou la sous-arborescence surveillé entraîne le retour d’une opération d’attente de notification de modification.

[out, optional] lpBytesReturned

Pour les appels synchrones, ce paramètre reçoit le nombre d’octets transférés dans le paramètre lpBuffer . Pour les appels asynchrones, ce paramètre n’est pas défini. Vous devez utiliser une technique de notification asynchrone pour récupérer le nombre d’octets transférés.

[in, out, optional] lpOverlapped

Pointeur vers une structure CHEVAUCHEMENT QUI fournit des données à utiliser pendant l’opération asynchrone. Sinon, cette valeur est NULL. Les membres Offset et OffsetHigh de cette structure ne sont pas utilisés.

[in, optional] lpCompletionRoutine

Pointeur vers une routine d’achèvement à appeler lorsque l’opération a été terminée ou annulée et que le thread appelant est dans un état d’attente pouvant être alerté. Pour plus d’informations sur cette routine d’achèvement, consultez FileIOCompletionRoutine.

[in] ReadDirectoryNotifyInformationClass

Type d’informations que ReadDirectoryChangesExW doit écrire dans la mémoire tampon vers laquelle pointe le paramètre lpBuffer . Spécifiez ReadDirectoryNotifyInformation pour indiquer que les informations doivent être constituées de structures FILE_NOTIFY_INFORMATION , ou ReadDirectoryNotifyExtendedInformation pour indiquer que les informations doivent être constituées de structures FILE_NOTIFY_EXTENDED_INFORMATION .

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro. Pour les appels synchrones, cela signifie que l’opération a réussi. Pour les appels asynchrones, cela indique que l’opération a été correctement mise en file d’attente.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Si le redirecteur réseau ou le système de fichiers cible ne prend pas en charge cette opération, la fonction échoue avec ERROR_INVALID_FUNCTION.

Remarques

Pour obtenir un handle dans un répertoire, utilisez la fonction CreateFile avec l’indicateur FILE_FLAG_BACKUP_SEMANTICS .

Un appel à ReadDirectoryChangesExW peut être effectué de manière synchrone ou asynchrone. Pour spécifier l’achèvement asynchrone, ouvrez le répertoire avec CreateFile comme indiqué ci-dessus, mais spécifiez également l’attribut FILE_FLAG_OVERLAPPED dans le paramètre dwFlagsAndAttributes . Spécifiez ensuite une structure OVERLAPPED lorsque vous appelez ReadDirectoryChangesExW.

Lorsque vous appelez ReadDirectoryChangesExW pour la première fois, le système alloue une mémoire tampon pour stocker les informations de modification. Cette mémoire tampon est associée au handle de répertoire jusqu’à ce qu’elle soit fermée et que sa taille ne change pas pendant sa durée de vie. Les modifications de répertoire qui se produisent entre les appels à cette fonction sont ajoutées à la mémoire tampon, puis retournées avec l’appel suivant. Si la mémoire tampon dépasse, ReadDirectoryChangesExW retourne toujours true, mais le contenu entier de la mémoire tampon est ignoré et le paramètre lpBytesReturned est égal à zéro, ce qui indique que votre mémoire tampon était trop petite pour contenir toutes les modifications qui ont eu lieu.

En cas d’achèvement synchrone réussi, le paramètre lpBuffer est une mémoire tampon mise en forme et le nombre d’octets écrits dans la mémoire tampon est disponible dans lpBytesReturned. Si le nombre d’octets transférés est égal à zéro, la mémoire tampon était trop grande pour que le système soit allouée ou trop petite pour fournir des informations détaillées sur toutes les modifications qui se sont produites dans le répertoire ou la sous-arborescence. Dans ce cas, vous devez calculer les modifications en énumérant le répertoire ou la sous-arborescence.

Pour l’achèvement asynchrone, vous pouvez recevoir une notification de l’une des trois manières suivantes :

Utilisation de la fonction GetOverlappedResult . Pour recevoir une notification via GetOverlappedResult, ne spécifiez pas de routine d’achèvement dans le paramètre lpCompletionRoutine . Veillez à définir le membre hEvent de la structure OVERLAPPED sur un événement unique.
Utilisation de la fonction GetQueuedCompletionStatus . Pour recevoir une notification via GetQueuedCompletionStatus, ne spécifiez pas de routine d’achèvement dans lpCompletionRoutine. Associez le handle de répertoire hDirectory à un port d’achèvement en appelant la fonction CreateIoCompletionPort .
Utilisation d’une routine d’achèvement. Pour recevoir une notification via une routine d’achèvement, n’associez pas le répertoire à un port d’achèvement. Spécifiez une routine d’achèvement dans lpCompletionRoutine. Cette routine est appelée chaque fois que l’opération a été terminée ou annulée alors que le thread est dans un état d’attente pouvant être alerté. Le membre hEvent de la structure OVERLAPPED n’étant pas utilisé par le système, vous pouvez l’utiliser vous-même.

Pour plus d’informations, consultez E/S synchrones et asynchrones.

ReadDirectoryChangesExW échoue avec ERROR_INVALID_PARAMETER lorsque la longueur de la mémoire tampon est supérieure à 64 Ko et que l’application surveille un répertoire sur le réseau. Cela est dû à une limitation de taille des paquets avec les protocoles de partage de fichiers sous-jacents.

ReadDirectoryChangesExW échoue avec ERROR_NOACCESS lorsque la mémoire tampon n’est pas alignée sur une limite DWORD .

ReadDirectoryChangesExW échoue avec ERROR_NOTIFY_ENUM_DIR lorsque le système n’a pas pu enregistrer toutes les modifications apportées au répertoire. Dans ce cas, vous devez calculer les modifications en énumérant le répertoire ou la sous-arborescence.

Si vous avez ouvert le fichier à l’aide du nom court, vous pouvez recevoir des notifications de modification pour le nom court.

ReadDirectoryChangesExW est actuellement pris en charge uniquement pour le système de fichiers NTFS.

Opérations traitées

S’il existe une transaction liée au handle d’annuaire, les notifications suivent les règles d’isolation de transaction appropriées.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10, version 1709 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2019 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll