NotifyRouteChange, fonction (iphlpapi.h)

Article
08/24/2023

La fonction NotifyRouteChange provoque l’envoi d’une notification à l’appelant chaque fois qu’une modification se produit dans la table de routage IPv4.

Syntaxe

IPHLPAPI_DLL_LINKAGE DWORD NotifyRouteChange(
  [out] PHANDLE      Handle,
  [in]  LPOVERLAPPED overlapped
);

Paramètres

[out] Handle

Pointeur vers une variable HANDLE qui reçoit un handle à utiliser dans une notification asynchrone.

[in] overlapped

Pointeur vers une structure CHEVAUCHEMENT QUI avertit l’appelant de toute modification apportée à la table de routage.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR si l’appelant spécifie NULL pour les paramètres Handle et qui se chevauchent . Si l’appelant spécifie des paramètres non NULL , la valeur de retour de réussite est ERROR_IO_PENDING. Si la fonction échoue, utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Code de retour	Description
ERROR_CANCELLED	Le contexte étant en cours d’annulation, l’appel a été annulé immédiatement.
ERROR_INVALID_PARAMETER	Un paramètre non valide a été passé. Cette erreur est retournée si les paramètres Handle et chevauchés ne sont pas NULL, mais que la mémoire spécifiée par les paramètres d’entrée ne peut pas être écrite par le processus appelant. Cette erreur est également retournée si le client a déjà effectué une demande de notification de modification, de sorte que cette demande en double échoue.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible était insuffisante pour terminer l’opération.
ERROR_NOT_SUPPORTED	Cette erreur est retournée sur les versions de Windows où cette fonction n’est pas prise en charge, comme Windows 98/95 et Windows NT 4.0.

Notes

The
La fonction NotifyRouteChange peut être appelée de deux façons :

Méthode synchrone
Méthode asynchrone

Si l’appelant spécifie NULL pour les paramètres Handle et qui se chevauchent , l’appel à NotifyRouteChange est synchrone et se bloque jusqu’à ce qu’une modification de la table de routage IPv4 se produise. Dans ce cas, si une modification se produit, la fonction NotifyRouteChange se termine pour indiquer qu’une modification s’est produite.

Si la fonction NotifyRouteChange est appelée de manière synchrone, une notification est envoyée lors de la modification de routage IPv4 suivante jusqu’à ce que l’application se termine.

Si l’appelant spécifie une variable de handle et une structure CHEVAUCHEMENT, l’appelant peut utiliser le handle retourné avec la structure OVERLAPPED pour recevoir une notification asynchrone des modifications de table de routage IPv4. Pour plus d’informations sur l’utilisation du handle et de la structure OVERLAPPED pour recevoir des notifications, consultez les rubriques suivantes :

Si l’application reçoit une notification et nécessite une notification pour la modification suivante, la fonction NotifyRouteChange doit être appelée à nouveau.

La fonction CancelIPChangeNotify annule la notification des modifications d’adresse IP et de routage précédemment demandées avec des appels réussis aux fonctions NotifyAddrChange ou NotifyRouteChange .

Une fois qu’une application a été informée d’une modification, l’application peut appeler la fonction GetIpForwardTable ou GetIpForwardTable2 pour récupérer la table de routage IPv4 afin de déterminer ce qui a changé. Si l’application est avertie et nécessite une notification pour la modification suivante, la fonction NotifyRouteChange doit être appelée à nouveau.

Si la fonction NotifyRouteChange est appelée de manière asynchrone, une notification est envoyée lors de la modification d’itinéraire IPv4 suivante jusqu’à ce que l’application annule la notification en appelant la fonction CancelIPChangeNotify ou que l’application se termine. Si l’application s’arrête, le système annule automatiquement l’inscription pour la notification. Il est toujours recommandé qu’une application annule explicitement toute notification avant son arrêt.

L’inscription d’une notification ne persiste pas au cours d’un arrêt ou d’un redémarrage du système.

Sur Windows Vista et versions ultérieures, la fonction NotifyRouteChange2 peut être utilisée pour s’inscrire afin d’être averti des modifications apportées à la table de routage IPv6 sur l’ordinateur local.

Exemples

L’exemple suivant attend qu’une modification se produise dans la table de routage IP.

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <windows.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

void main()
{
  OVERLAPPED overlap;
  DWORD ret;
    
  HANDLE hand = NULL;
  overlap.hEvent = WSACreateEvent();

  ret = NotifyRouteChange(&hand, &overlap);

  if (ret != NO_ERROR)
  {
    if (WSAGetLastError() != WSA_IO_PENDING)
    {
      printf("NotifyRouteChange error...%d\n", WSAGetLastError());            
      return;
    }
  }

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("Routing table changed..\n");
}

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	iphlpapi.h
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll