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	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 changement, la création ou la suppression d'un nom de 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_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.

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

Voir aussi

Fonctions de gestion d’annuaire

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW