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.
[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.
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 |