FindFirstChangeNotificationA, fonction (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é lui-même.
Cette fonction n’indique pas la modification qui 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 à regarder.
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 larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez nommage des fichiers, des chemins d’accès et des espaces de noms.
Pourboire
À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.
[in] bWatchSubtree
Si ce paramètre est TRUE, la fonction surveille l’arborescence de répertoires enracinée dans le répertoire spécifié ; si elle est FALSE, elle surveille uniquement le répertoire spécifié.
[in] dwNotifyFilter
Conditions de filtre qui répondent à une attente de notification de modification. Ce paramètre peut être une ou plusieurs des valeurs suivantes.
Valeur de retour
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’erreur étendues, appelez GetLastError.
Remarques
Les fonctions d’attente peuvent surveiller le répertoire ou la sous-arborescence spécifié à 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 surveillé ou la sous-arborescence.
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 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 | Supporté |
|---|---|
| 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 parallèle (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 lors de la pause/reprise csvFs.
Exemples
Pour obtenir un exemple, consultez Obtention du répertoire Change_Notifications.
Note
L’en-tête fileapi.h définit FindFirstChangeNotification comme 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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | fileapi.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |