NotifyAddrChange-Funktion (iphlpapi.h)

Artikel
08/24/2023

Die NotifyAddrChange-Funktion bewirkt, dass eine Benachrichtigung an den Aufrufer gesendet wird, wenn eine Änderung in der Tabelle auftritt, die IPv4-Adressen Schnittstellen zuordnet.

Syntax

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

Parameter

[out] Handle

Ein Zeiger auf eine HANDLE-Variable , die ein Dateihandle zur Verwendung in einem nachfolgenden Aufruf der GetOverlappedResult-Funktion empfängt .

Warnung Schließen Sie dieses Handle nicht, und ordnen Sie es keinem Vervollständigungsport zu.

[in] overlapped

Ein Zeiger auf eine OVERLAPPED-Struktur , die den Aufrufer über Änderungen in der Tabelle benachrichtigt, die IP-Adressen Schnittstellen zuordnen.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR, wenn der Aufrufer NULL für die Handle - und überlappenden Parameter angibt. Wenn der Aufrufer Parameter ohne NULL angibt, ist der Rückgabewert für erfolg ERROR_IO_PENDING.

Wenn die Funktion fehlschlägt, verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Rückgabecode	Beschreibung
ERROR_CANCELLED	Der Kontext wird aufgehoben, sodass der Aufruf sofort abgebrochen wurde.
ERROR_INVALID_PARAMETER	Es wurde ein ungültiger Parameter übergeben. Dieser Fehler wird zurückgegeben, wenn sowohl der Handle - als auch der überlappende Parameter nicht NULL sind, aber der durch die Eingabeparameter angegebene Arbeitsspeicher nicht vom aufrufenden Prozess geschrieben werden kann. Dieser Fehler wird auch zurückgegeben, wenn der Client bereits eine Änderungsbenachrichtigungsanforderung gestellt hat, sodass bei dieser doppelten Anforderung ein Fehler auftritt.
ERROR_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.
ERROR_NOT_SUPPORTED	Dieser Fehler wird für Windows-Versionen zurückgegeben, in denen diese Funktion nicht unterstützt wird, z. B. Windows 98/95 und Windows NT 4.0.

Hinweise

The
NotifyAddrChange-Funktion kann auf zwei Arten aufgerufen werden:

Synchrone Methode
Asynchrone Methode

Wenn der Aufrufer NULL für die Parameter Handle und überlappende Parameter angibt, ist der Aufruf von NotifyAddrChange synchron und blockiert, bis eine ÄNDERUNG der IP-Adresse eintritt. Wenn in diesem Fall eine Änderung auftritt, wird die NotifyAddrChange-Funktion abgeschlossen, um anzugeben, dass eine Änderung aufgetreten ist.

Wenn die NotifyAddrChange-Funktion synchron aufgerufen wird, wird bei der nächsten IPv4-Adressänderung eine Benachrichtigung gesendet, bis die Anwendung beendet wird.

Wenn der Aufrufer eine Handle-Variable und eine OVERLAPPED-Struktur angibt, ist der NotifyAddrChange-Funktionsaufruf asynchron, und der Aufrufer kann das zurückgegebene Handle mit der OVERLAPPED-Struktur verwenden, um asynchrone Benachrichtigungen über IPv4-Adressänderungen mithilfe der GetOverlappedResult-Funktion zu empfangen. Informationen zur Verwendung des Handle und der OVERLAPPED-Struktur zum Empfangen von Benachrichtigungen finden Sie in den folgenden Themen:

Die CancelIPChangeNotify-Funktion bricht die Benachrichtigung über IPv4-Adress- und Routingänderungen ab, die zuvor mit erfolgreichen Aufrufen der Funktionen NotifyAddrChange oder NotifyRouteChange angefordert wurden.

Sobald eine Anwendung über eine Änderung benachrichtigt wurde, kann die Anwendung die GetIpAddrTable - oder GetAdaptersAddresses-Funktion aufrufen, um die Tabelle der IPv4-Adressen abzurufen, um zu bestimmen, was geändert wurde. Wenn die Anwendung benachrichtigt wird und eine Benachrichtigung für die nächste Änderung erfordert, muss die NotifyAddrChange-Funktion erneut aufgerufen werden.

Wenn die NotifyAddrChange-Funktion asynchron aufgerufen wird, wird bei der nächsten IPv4-Adressänderung eine Benachrichtigung gesendet, bis entweder die Anwendung die Benachrichtigung durch Aufrufen der Funktion CancelIPChangeNotify abbricht oder die Anwendung beendet wird. Wenn die Anwendung beendet wird, bricht das System die Registrierung für die Benachrichtigung automatisch ab. Es wird weiterhin empfohlen, dass eine Anwendung jede Benachrichtigung explizit abbricht, bevor sie beendet wird.

Jede Registrierung für eine Benachrichtigung bleibt nicht während eines Herunterfahrens oder Neustarts des Systems erhalten.

Unter Windows Vista und höher kann die NotifyIpInterfaceChange-Funktion verwendet werden, um sich für Änderungen an IPv4- und IPv6-Schnittstellen auf dem lokalen Computer zu registrieren.

Beispiele

Im folgenden Beispiel wird auf eine Änderung in der Tabelle gewartet, die IP-Adressen Schnittstellen zuordnet.

#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");
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	iphlpapi.h
Bibliothek	Iphlpapi.lib
DLL	Iphlpapi.dll