NotifyAddrChange, fonction (iphlpapi.h)

Article
08/24/2023

La fonction NotifyAddrChange entraîne l’envoi d’une notification à l’appelant chaque fois qu’une modification se produit dans la table qui mappe les adresses IPv4 aux interfaces.

Syntaxe

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

Paramètres

[out] Handle

Pointeur vers une variable HANDLE qui reçoit un handle de fichier à utiliser dans un appel ultérieur à la fonction GetOverlappedResult .

Avertissement Ne fermez pas ce handle et ne l’associez pas à un port d’achèvement.

[in] overlapped

Pointeur vers une structure CHEVAUCHEMENT QUI avertit l’appelant de toute modification apportée à la table qui mappe les adresses IP aux interfaces.

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 NotifyAddrChange 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 à NotifyAddrChange est synchrone et se bloque jusqu’à ce qu’un changement d’adresse IP se produise. Dans ce cas, si une modification se produit, la fonction NotifyAddrChange se termine pour indiquer qu’une modification s’est produite.

Si la fonction NotifyAddrChange est appelée de façon synchrone, une notification est envoyée lors du changement d’adresse IPv4 suivant jusqu’à ce que l’application se termine.

Si l’appelant spécifie une variable de handle et une structure OVERLAPPED , l’appel de la fonction NotifyAddrChange est asynchrone et l’appelant peut utiliser le handle retourné avec la structure OVERLAPPED pour recevoir une notification asynchrone des modifications d’adresse IPv4 à l’aide de la fonction GetOverlappedResult . Pour plus d’informations sur l’utilisation du handle et de la structure OVERLAPPED pour recevoir des notifications, consultez les rubriques suivantes :

La fonction CancelIPChangeNotify annule la notification des modifications d’adresse IPv4 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é avertie d’une modification, l’application peut appeler la fonction GetIpAddrTable ou GetAdaptersAddresses pour récupérer la table des adresses 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 NotifyAddrChange doit être appelée à nouveau.

Si la fonction NotifyAddrChange est appelée de manière asynchrone, une notification est envoyée lors du changement d’adresse IPv4 suivant 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 NotifyIpInterfaceChange peut être utilisée pour s’inscrire afin d’être averti des modifications apportées aux interfaces IPv4 et IPv6 sur l’ordinateur local.

Exemples

L’exemple suivant attend qu’une modification se produise dans le tableau qui mappe les adresses IP aux interfaces.

#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 = NotifyAddrChange(&hand, &overlap);

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

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("IP Address 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