Fonction FindFirstChangeNotificationA (fileapi.h)
Crée un handle de notification de modification et configure les conditions de filtre de notification de modification initiales. Une attente sur un handle de notification réussit lorsqu’une modification correspondant aux conditions de filtre se produit dans le répertoire ou sous-arborescence spécifié. La fonction ne signale pas les modifications apportées au répertoire spécifié.
Cette fonction n’indique pas la modification qui a satisfait à la condition d’attente. Pour récupérer des informations sur la modification spécifique dans le cadre de la notification, utilisez le
Fonction ReadDirectoryChangesW .
Syntaxe
HANDLE FindFirstChangeNotificationA(
[in] LPCSTR lpPathName,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter
);
Paramètres
[in] lpPathName
Chemin d’accès complet du répertoire à surveiller.
Il ne peut pas s’agir d’un chemin relatif ou d’une chaîne vide.
Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères de large, ajoutez « \\?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.
Conseil
À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation de MAX_PATH sans précédencer « \?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .
[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é ; s’il a la valeur FALSE, il surveille uniquement le répertoire spécifié.
[in] dwNotifyFilter
Les conditions de filtre qui répondent à une notification de modification attendent. Ce paramètre peut être une ou plusieurs des valeurs suivantes.
Valeur retournée
Si la fonction réussit, la valeur de retour est un handle pour un objet de notification de modification de recherche.
Si la fonction échoue, la valeur de retour est INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Notes
Les fonctions d’attente peuvent surveiller le répertoire ou la sous-arborescence spécifiés à l’aide du handle retourné par la fonction FindFirstChangeNotification . Une attente est satisfaite lorsque l’une des conditions de filtre se produit dans le répertoire ou la sous-arborescence surveillé.
Une fois l’attente satisfaite, l’application peut répondre à cette condition et continuer à surveiller le répertoire en appelant la fonction FindNextChangeNotification et la fonction d’attente appropriée. Lorsque le handle n’est plus nécessaire, il peut être fermé à l’aide de la fonction FindCloseChangeNotification .
Les notifications peuvent ne pas être retournées lors de l’appel de FindFirstChangeNotification pour un système de fichiers distant.
Comportement de lien symbolique : si le chemin pointe vers un lien symbolique, le handle de notification est créé pour la cible.
Si une application s’est inscrite pour recevoir des notifications de modification pour un répertoire qui contient des liens symboliques, l’application n’est avertie que lorsque les liens symboliques ont été modifiés, et non les fichiers cibles.
Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.
| Technologie | Prise en charge |
|---|---|
| Protocole SMB (Server Message Block) 3.0 | Oui |
| Basculement transparent SMB 3.0 (TFO) | Oui |
| SMB 3.0 avec partages de fichiers avec montée en puissance sortante (SO) | Oui |
| Cluster Shared Volume File System (CsvFS) | Voir la remarque |
| Système de fichiers résilient (ReFS) | Oui |
L’application peut rencontrer des faux positifs sur la pause/reprise csvFs.
Exemples
Pour obtenir un exemple, consultez Obtention d’un Change_Notifications d’annuaire.
Notes
L’en-tête fileapi.h définit FindFirstChangeNotification en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
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] |
| Plateforme cible | Windows |
| En-tête | fileapi.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |