Partager via


ReadDirectoryChangesW, fonction (winbase.h)

Récupère les informations qui décrivent les changements dans le répertoire 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 ReadDirectoryChangesW(
  [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
);

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 les résultats de lecture doivent être retournés. La structure de cette mémoire tampon est définie par la structure FILE_NOTIFY_INFORMATION . 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.

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 à ReadDirectoryChangesW 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 ReadDirectoryChangesW.

Lorsque vous appelez ReadDirectoryChangesW 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, ReadDirectoryChangesW retourne toujours true, mais tout le contenu 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 se sont produites.

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.

ReadDirectoryChangesW é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.

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

ReadDirectoryChangesW é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.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie Prise en charge
Protocole Server Message Block (SMB) 3.0 Oui
Basculement transparent SMB 3.0 (TFO) Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) Oui
Système de fichiers du volume partagé de cluster (CsvFS) Oui
Système de fichiers résilient (ReFS) Oui
 

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

   
Client minimal pris en charge Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête winbase.h (inclure Windows.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

CreateFile

CreateIoCompletionPort

Fonctions de gestion des répertoires

FILE_NOTIFY_INFORMATION

FileIOCompletionRoutine

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED