Funzione NotifyRouteChange (iphlpapi.h)

Articolo
08/24/2023

La funzione NotifyRouteChange causa l'invio di una notifica al chiamante ogni volta che si verifica una modifica nella tabella di routing IPv4.

Sintassi

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

Parametri

[out] Handle

Puntatore a una variabile HANDLE che riceve un handle da usare nella notifica asincrona.

[in] overlapped

Puntatore a una struttura OVERLAPPED che informa il chiamante di eventuali modifiche nella tabella di routing.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NO_ERROR se il chiamante specifica NULL per i parametri Handle e sovrapposti . Se il chiamante specifica parametri non NULL , il valore restituito per esito positivo è ERROR_IO_PENDING. Se la funzione ha esito negativo, usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Codice restituito	Descrizione
ERROR_CANCELLED	Il contesto viene deregisterato, quindi la chiamata è stata annullata immediatamente.
ERROR_INVALID_PARAMETER	È stato passato un parametro non valido. Questo errore viene restituito se i parametri handle e sovrapposti non sono NULL, ma la memoria specificata dai parametri di input non può essere scritta dal processo chiamante. Questo errore viene restituito anche se il client ha già effettuato una richiesta di notifica di modifica, quindi questa richiesta duplicata avrà esito negativo.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione.
ERROR_NOT_SUPPORTED	Questo errore viene restituito nelle versioni di Windows in cui questa funzione non è supportata, ad esempio Windows 98/95 e Windows NT 4.0.

Commenti

The
La funzione NotifyRouteChange può essere chiamata in due modi:

Metodo sincrono
Metodo asincrono

Se il chiamante specifica NULL per i parametri Handle e sovrapposti , la chiamata a NotifyRouteChange è sincrona e bloccherà finché non si verifica una modifica della tabella di routing IPv4. In questo caso, se si verifica una modifica, la funzione NotifyRouteChange viene completata per indicare che si è verificata una modifica.

Se la funzione NotifyRouteChange viene chiamata in modo sincrono, verrà inviata una notifica alla successiva modifica del routing IPv4 fino al termine dell'applicazione.

Se il chiamante specifica una variabile handle e una struttura OVERLAPPED , il chiamante può usare l'handle restituito con la struttura OVERLAPPED per ricevere una notifica asincrona della tabella di routing IPv4. Per informazioni sull'uso della struttura handle e OVERLAPPED per ricevere notifiche, vedere gli argomenti seguenti:

Se l'applicazione riceve una notifica e richiede una notifica per la modifica successiva, la funzione NotifyRouteChange deve essere chiamata di nuovo.

La funzione CancelIPChangeNotify annulla la notifica dell'indirizzo IP e le modifiche di route richieste in precedenza con chiamate riuscite alle funzioni NotifyAddrChange o NotifyRouteChange.

Una volta notificata una modifica, l'applicazione può quindi chiamare la funzione GetIpForwardTable o GetIpForwardTable2 per recuperare la tabella di routing IPv4 per determinare cosa è stato modificato. Se l'applicazione riceve una notifica e richiede la notifica per la modifica successiva, la funzione NotifyRouteChange deve essere chiamata di nuovo.

Se la funzione NotifyRouteChange viene chiamata in modo asincrono, verrà inviata una notifica nella successiva modifica della route IPv4 fino a quando l'applicazione annulla la notifica chiamando la funzione CancelIPChangeNotify o l'applicazione termina. Se l'applicazione termina, il sistema annulla automaticamente la registrazione per la notifica. È comunque consigliabile annullare esplicitamente qualsiasi notifica prima di terminare un'applicazione.

Qualsiasi registrazione per una notifica non persiste in un sistema arrestato o riavviato.

In Windows Vista e versioni successive, la funzione NotifyRouteChange2 può essere usata per la registrazione per ricevere una notifica per le modifiche apportate alla tabella di routing IPv6 nel computer locale.

Esempio

L'esempio seguente attende che si verifichi una modifica nella tabella di routing 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");
}

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	iphlpapi.h
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll