NotifyRouteChange-Funktion (iphlpapi.h)

Artikel
08/24/2023

Die NotifyRouteChange-Funktion bewirkt, dass eine Benachrichtigung an den Aufrufer gesendet wird, wenn eine Änderung in der IPv4-Routingtabelle auftritt.

Syntax

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

Parameter

[out] Handle

Ein Zeiger auf eine HANDLE-Variable , die ein Handle empfängt, das in asynchronen Benachrichtigungen verwendet werden soll.

[in] overlapped

Ein Zeiger auf eine OVERLAPPED-Struktur , die den Aufrufer über Änderungen in der Routingtabelle benachrichtigt.

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 Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Rückgabecode	Beschreibung
ERROR_CANCELLED	Die Registrierung des Kontexts 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 diese doppelte Anforderung fehlschlägt.
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 Versionen von Windows zurückgegeben, bei denen diese Funktion nicht unterstützt wird, z. B. Windows 98/95 und Windows NT 4.0.

Hinweise

The
Die NotifyRouteChange-Funktion kann auf zwei Arten aufgerufen werden:

Synchrone Methode
Asynchrone Methode

Wenn der Aufrufer NULL für die Handle - und überlappenden Parameter angibt, ist der Aufruf von NotifyRouteChange synchron und wird blockiert, bis eine Änderung der IPv4-Routingtabelle auftritt. In diesem Fall, wenn eine Änderung auftritt, wird die NotifyRouteChange-Funktion abgeschlossen, um anzugeben, dass eine Änderung erfolgt ist.

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

Wenn der Aufrufer eine Handle-Variable und eine OVERLAPPED-Struktur angibt, kann der Aufrufer das zurückgegebene Handle mit der OVERLAPPED-Struktur verwenden, um asynchrone Benachrichtigungen über IPv4-Routingtabellenänderungen zu erhalten. In den folgenden Themen finden Sie Informationen zur Verwendung des Handles und der OVERLAPPED-Struktur zum Empfangen von Benachrichtigungen:

Wenn die Anwendung eine Benachrichtigung empfängt und eine Benachrichtigung für die nächste Änderung erfordert, muss die NotifyRouteChange-Funktion erneut aufgerufen werden.

Die CancelIPChangeNotify-Funktion bricht die Benachrichtigung über die IP-Adresse ab und leitet Änderungen weiter, die zuvor mit erfolgreichen Aufrufen der Funktionen NotifyAddrChange oder NotifyRouteChange angefordert wurden.

Sobald eine Anwendung über eine Änderung benachrichtigt wurde, kann die Anwendung die Funktion GetIpForwardTable oder GetIpForwardTable2 aufrufen, um die IPv4-Routingtabelle 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 NotifyRouteChange-Funktion erneut aufgerufen werden.

Wenn die NotifyRouteChange-Funktion asynchron aufgerufen wird, wird bei der nächsten IPv4-Routenä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 wird nicht über ein Herunterfahren oder Neustarten des Systems hinweg beibehalten.

Unter Windows Vista und höher kann die NotifyRouteChange2-Funktion verwendet werden, um über Änderungen an der IPv6-Routingtabelle auf dem lokalen Computer benachrichtigt zu werden.

Beispiele

Im folgenden Beispiel wird auf eine Änderung in der IP-Routingtabelle gewartet.

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

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