NotifyRouteChange2, fonction (netioapi.h)

Article
08/25/2023

La fonction NotifyRouteChange2 s’inscrit pour être avertie des modifications apportées aux entrées d’itinéraire IP sur un ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
  [in]      ADDRESS_FAMILY             AddressFamily,
  [in]      PIPFORWARD_CHANGE_CALLBACK Callback,
  [in]      PVOID                      CallerContext,
  [in]      BOOLEAN                    InitialNotification,
  [in, out] HANDLE                     *NotificationHandle
);

Paramètres

[in] AddressFamily

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 Kit de développement logiciel (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_INET	Inscrivez-vous uniquement aux notifications de modification de routage IPv4.
AF_INET6	Inscrivez-vous uniquement aux notifications de modification de routage IPv6.
AF_UNSPEC	Inscrivez-vous aux notifications de modification de route IPv4 et IPv6.

[in] Callback

Pointeur vers la fonction à appeler lorsqu’une modification se produit. Cette fonction est appelée lors de la réception d’une notification d’itinéraire IP.

[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’itinéraire IP.

[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 entrée de route 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.

Notes

La fonction NotifyRouteChange2 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 NotifyRouteChange2 lors de l’inscription aux notifications.
IN PMIB_IPFORWARD_ROW2 Row OPTIONAL	Pointeur vers l’entrée MIB_IPFORWARD_ROW2 pour l’entrée d’itinéraire IP 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é à NotifyRouteChange2 a la valeur 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 NotifyRouteChange2 . Si la fonction de rappel se trouve dans une DLL distincte, la DLL doit être chargée avant d’appeler la fonction NotifyRouteChange2 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_IPFORWARD_ROW2 passée dans le paramètre Row contient des données incomplètes. Les informations retournées dans la structure MIB_IPFORWARD_ROW2 ne sont que suffisantes pour qu’une application puisse appeler la fonction GetIpForwardEntry2 pour interroger des informations complètes sur l’itinéraire IP modifié. Lorsque la fonction de rappel est reçue, une application doit allouer une structure de MIB_IPFORWARD_ROW2 et l’initialiser avec les membres DestinationPrefix, NextHop, InterfaceLuid et InterfaceIndex dans la structure MIB_IPFORWARD_ROW2 pointée par le paramètre Row reçu. Un pointeur vers cette structure de MIB_IPFORWARD_ROW2 nouvellement initialisée doit être passé à la fonction GetIpForwardEntry2 pour récupérer des informations complètes sur l’itinéraire IP modifié.

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 .

Une fois que la fonction NotifyRouteChange2 est appelée pour s’inscrire aux notifications de modification, ces notifications continuent d’ê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 aux notifications de modification ne persiste pas si le système est arrêté ou redémarré.

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

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.

Spécifications


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