Fonction NotifyIpInterfaceChange (netioapi.h)

Article
02/29/2024

La fonction NotifyIpInterfaceChange s’inscrit pour être avertie des modifications apportées à toutes les interfaces IP, interfaces IPv4 ou interfaces IPv6 sur un ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyIpInterfaceChange(
  [in]      ADDRESS_FAMILY               Family,
  [in]      PIPINTERFACE_CHANGE_CALLBACK Callback,
  [in]      PVOID                        CallerContext,
  [in]      BOOLEAN                      InitialNotification,
  [in, out] HANDLE                       *NotificationHandle
);

Paramètres

[in] Family

Famille d’adresses sur laquelle s’inscrire aux notifications de modification.

Les valeurs possibles pour la famille d’adresses sont répertoriées dans le fichier d’en-tête Winsock2.h . Notez que les valeurs de la famille d’adresses AF_ et des constantes de famille de protocole PF_ sont identiques (par exemple , AF_INET et PF_INET), de sorte que l’une ou l’autre constante peut être utilisée.

Sur le SDK Windows publié pour Windows Vista et versions ultérieures, la organization des fichiers d’en-tête a changé et les valeurs possibles pour ce membre sont définies dans le fichier d’en-tête Ws2def.h. Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.

Les valeurs actuellement prises en charge sont AF_INET, AF_INET6 et AF_UNSPEC.

Valeur	Signification
AF_UNSPEC 0	La famille d’adresses n’est pas spécifiée. Lorsque ce paramètre est spécifié, cette fonction s’inscrit pour les notifications de modification IPv4 et IPv6.
AF_INET 2	Famille d’adresses IPv4 (Internet Protocol version 4). Lorsque ce paramètre est spécifié, cette fonction s’inscrit uniquement pour les notifications de modification IPv4.
AF_INET6 23	Famille d’adresses IPv6 (Internet Protocol version 6). Lorsque ce paramètre est spécifié, cette fonction s’inscrit uniquement pour les notifications de modification IPv6.

[in] Callback

Pointeur vers la fonction à appeler lorsqu’une modification se produit. Cette fonction est appelée lorsqu’une notification d’interface est reçue.

[in] CallerContext

Contexte utilisateur passé à la fonction de rappel spécifiée dans le paramètre Callback lors de la réception d’une notification d’interface.

[in] InitialNotification

Valeur qui indique si le rappel doit être appelé immédiatement après la fin de l’inscription pour la notification de modification. Cette notification initiale n’indique pas qu’une modification a été apportée à une interface IP. L’objectif de ce paramètre est de fournir la confirmation que le rappel est inscrit.

[in, out] NotificationHandle

Pointeur utilisé pour retourner un handle qui peut être utilisé ultérieurement pour annuler l’inscription de la notification de modification. En cas de réussite, un handle de notification est retourné dans ce paramètre. Si une erreur se produit, NULL est retourné.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_INVALID_HANDLE	Une erreur interne s’est produite lorsqu’un handle non valide a été rencontré.
ERROR_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si le paramètre Family n’était pas AF_INET, AF_INET6 ou AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	La mémoire était insuffisante.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Remarques

La fonction NotifyIpInterfaceChange est définie sur Windows Vista et versions ultérieures.

Le paramètre Family doit être défini sur AF_INET, AF_INET6 ou AF_UNSPEC.

L’appel de la fonction de rappel spécifiée dans le paramètre Callback est sérialisé. La fonction de rappel doit être définie comme une fonction de type VOID. Les paramètres passés à la fonction de rappel sont les suivants :

Paramètre	Description
IN PVOID CallerContext	Paramètre CallerContext passé à la fonction NotifyIpInterfaceChange lors de l’inscription aux notifications.
IN PMIB_IPINTERFACE_ROW Row OPTIONAL	Pointeur vers l’entrée MIB_IPINTERFACE_ROW pour l’interface qui a été modifiée. Ce paramètre est un pointeur NULL lorsque la valeur MIB_NOTIFICATION_TYPE passée dans le paramètre NotificationType à la fonction de rappel est définie sur MibInitialNotification. Cela ne peut se produire que si le paramètre InitialNotification passé à NotifyIpInterfaceChange a été défini sur TRUE lors de l’inscription aux notifications.
IN MIB_NOTIFICATION_TYPE NotificationType	Type de notification. Ce membre peut être l’une des valeurs du type d’énumération MIB_NOTIFICATION_TYPE défini dans le fichier d’en-tête Netioapi.h .

La fonction de rappel spécifiée dans le paramètre Callback doit être implémentée dans le même processus que l’application appelant la fonction NotifyIpInterfaceChange . Si la fonction de rappel se trouve dans une DLL distincte, la DLL doit être chargée avant d’appeler la fonction NotifyIpInterfaceChange pour s’inscrire aux notifications de modification.

Lorsque la fonction de rappel est reçue lorsqu’une modification se produit et que le paramètre Row n’a pas la valeur NULL, le pointeur vers la structure MIB_IPINTERFACE_ROW passée dans le paramètre Row contient des données incomplètes. Les informations retournées dans la structure MIB_IPINTERFACE_ROW ne sont que suffisantes pour qu’une application puisse appeler la fonction GetIpInterfaceEntry pour interroger des informations complètes sur l’interface IP modifiée. Lorsque la fonction de rappel est reçue, une application doit allouer une structure de MIB_IPINTERFACE_ROW et l’initialiser avec les membres Family, InterfaceLuid et InterfaceIndex dans la structure MIB_IPINTERFACE_ROW pointée vers le paramètre Row reçu. Un pointeur vers cette structure de MIB_IPINTERFACE_ROW nouvellement initialisée doit être passé à la fonction GetIpInterfaceEntry pour récupérer des informations complètes sur l’interface IP qui a été modifiée.

La mémoire pointée par le paramètre Row utilisé dans les indications de rappel est gérée par le système d’exploitation. Une application qui reçoit une notification ne doit jamais tenter de libérer la mémoire pointée par le paramètre Row .

Pour annuler l’inscription aux notifications de modification, appelez la fonction CancelMibChangeNotify2 en passant le paramètre NotificationHandle retourné par NotifyIpInterfaceChange.

Une application ne peut pas effectuer un appel à la fonction CancelMibChangeNotify2 à partir du contexte du thread qui exécute actuellement la fonction de rappel de notification pour le même paramètre NotificationHandle . Sinon, le thread qui exécute ce rappel entraîne un blocage. Par conséquent, la fonction CancelMibChangeNotify2 ne doit pas être appelée directement dans le cadre de la routine de rappel de notification. Dans une situation plus générale, un thread qui exécute la fonction CancelMibChangeNotify2 ne peut pas posséder une ressource sur laquelle le thread qui exécute une opération de rappel de notification attendrait, car cela entraînerait un interblocage similaire. La fonction CancelMibChangeNotify2 doit être appelée à partir d’un thread différent, sur lequel le thread qui reçoit le rappel de notification n’a pas de dépendances.

Une fois que la fonction NotifyIpInterfaceChange est appelée pour s’inscrire aux notifications de modification, ces notifications continueront à être envoyées jusqu’à ce que l’application annule l’inscription pour les notifications de modification ou que l’application se termine. Si l’application s’arrête, le système annule automatiquement toute inscription pour les notifications de modification. Il est toujours recommandé qu’une application annule explicitement l’inscription pour les notifications de modification avant son arrêt.

Toute inscription pour les notifications de modification n’est pas conservée au cours d’un arrêt ou d’un redémarrage du système.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	netioapi.h (include Iphlpapi.h)
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll