Fonction NotifyUnicastIpAddressChange (netioapi.h)

Article
08/25/2023

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

Syntaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_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 AF_ adressent les constantes famille et PF_ de famille de protocole 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, le 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_INET	Inscrivez-vous uniquement aux notifications de modification d’adresse IPv4 unicast.
AF_INET6	Inscrivez-vous uniquement aux notifications de modification d’adresse IPv6 unicast.
AF_UNSPEC	Inscrivez-vous aux notifications de modification d’adresse IPv4 et IPv6 unicast.

[in] Callback

Pointeur vers la fonction à appeler en cas de modification. Cette fonction est appelée lorsqu’une notification d’adresse IP unicast 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 s’est produite à une adresse IP unicast. 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 pour l’erreur retournée.

Remarques

La fonction NotifyUnicastIpAddressChange 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 NotifyUnicastIpAddressChange lors de l’inscription aux notifications.
LIGNE IN PMIB_UNICASTIPADDRESS_ROW FACULTATIF	Pointeur vers l’entrée MIB_UNICASTIPADDRESS_ROW pour l’adresse IP de unidiffusion 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é à NotifyUnicastIpAddressChange 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 NotifyUnicastIpAddressChange . Si la fonction de rappel se trouve dans une DLL distincte, la DLL doit être chargée avant d’appeler la fonction NotifyUnicastIpAddressChange pour s’inscrire aux notifications de modification.

Quand 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_UNICASTIPADDRESS_ROW passée dans le paramètre Row contient des données incomplètes. Les informations retournées dans la structure MIB_UNICASTIPADDRESS_ROW ne sont que suffisamment d’informations pour qu’une application puisse appeler la fonction GetUnicastIpAddressEntry pour interroger des informations complètes sur l’adresse IP modifiée. Lorsque la fonction de rappel est reçue, une application doit allouer une structure MIB_UNICASTIPADDRESS_ROW et l’initialiser avec les membres Address, InterfaceLuid et InterfaceIndex dans la structure MIB_UNICASTIPADDRESS_ROW pointée vers le paramètre Row reçu. Un pointeur vers cette structure de MIB_UNICASTIPADDRESS_ROW nouvellement initialisée doit être passé à la fonction GetUnicastIpAddressEntry pour récupérer des informations complètes sur l’adresse IP de unidiffusion qui a été modifiée.

La mémoire pointée vers 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 .

Une fois que la fonction NotifyUnicastIpAddressChange est appelée pour s’inscrire aux notifications de modification, ces notifications continueront d’être envoyées jusqu’à ce que l’application soit désinscrit pour les notifications de modification ou se termine. Si l’application se termine, le système désinscrira automatiquement toute inscription pour les notifications de modification. Il est toujours recommandé qu’une application désinscrire explicitement les notifications de modification avant qu’elle ne se termine.

Toute inscription pour les notifications de modification ne persiste pas si le système est arrêté ou redémarré.

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

Une application ne peut pas appeler 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 blocage similaire. La fonction CancelMibChangeNotify2 doit être appelée à partir d’un autre thread, sur lequel le thread qui reçoit le rappel de notification n’a pas de dépendances.

Configuration requise

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