Funzione NotifyRouteChange2 (netioapi.h)

Articolo
08/25/2023

La funzione NotifyRouteChange2 registra la notifica delle modifiche alle voci di route IP in un computer locale.

Sintassi

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
  [in]      ADDRESS_FAMILY             AddressFamily,
  [in]      PIPFORWARD_CHANGE_CALLBACK Callback,
  [in]      PVOID                      CallerContext,
  [in]      BOOLEAN                    InitialNotification,
  [in, out] HANDLE                     *NotificationHandle
);

Parametri

[in] AddressFamily

Famiglia di indirizzi in cui registrare le notifiche di modifica.

I valori possibili per la famiglia di indirizzi sono elencati nel file di intestazione Winsock2.h . Si noti che i valori per la famiglia di indirizzi AF_ e le costanti della famiglia di protocolli di PF_ sono identiche (ad esempio, AF_INET e PF_INET), in modo che sia possibile usare una costante.

In Windows SDK rilasciato per Windows Vista e versioni successive, l'organizzazione dei file di intestazione è stata modificata e i valori possibili per questo membro vengono definiti nel file di intestazione Ws2def.h . Si noti che il file di intestazione Ws2def.h viene incluso automaticamente in Winsock2.h e non deve mai essere usato direttamente.

I valori attualmente supportati sono AF_INET, AF_INET6 e AF_UNSPEC.

Valore	Significato
AF_INET	Registrare solo le notifiche di modifica della route IPv4.
AF_INET6	Registrare solo le notifiche di modifica della route IPv6.
AF_UNSPEC	Eseguire la registrazione per le notifiche di modifica della route IPv4 e IPv6.

[in] Callback

Puntatore alla funzione da chiamare quando si verifica una modifica. Questa funzione verrà richiamata quando viene ricevuta una notifica di route IP.

[in] CallerContext

Contesto utente passato alla funzione di callback specificata nel parametro Callback quando viene ricevuta una notifica di route IP.

[in] InitialNotification

Valore che indica se il callback deve essere richiamato immediatamente dopo il completamento della registrazione per la notifica delle modifiche. Questa notifica iniziale non indica una modifica apportata a una voce di route IP. Scopo di questo parametro per fornire la conferma che il callback è registrato.

[in, out] NotificationHandle

Puntatore usato per restituire un handle che può essere usato in un secondo momento per annullare la registrazione della notifica delle modifiche. In caso di esito positivo, viene restituito un handle di notifica in questo parametro. Se si verifica un errore, viene restituito NULL .

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NO_ERROR.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Si è verificato un errore interno in cui è stato rilevato un handle non valido.
ERROR_INVALID_PARAMETER	Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se il parametro Family non è AF_INET, AF_INET6 o AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente.
Altri	Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

La funzione NotifyRouteChange2 viene definita in Windows Vista e versioni successive.

Il parametro Family deve essere impostato su AF_INET, AF_INET6 o AF_UNSPEC.

La chiamata della funzione di callback specificata nel parametro Callback viene serializzata. La funzione di callback deve essere definita come funzione di tipo VOID. I parametri passati alla funzione callback includono quanto segue:

Parametro	Descrizione
IN PVOID CallerContext	Il parametro CallerContext passato alla funzione NotifyRouteChange2 durante la registrazione delle notifiche.
IN PMIB_IPFORWARD_ROW2 riga FACOLTATIVA	Puntatore alla voce MIB_IPFORWARD_ROW2 per la voce di route IP modificata. Questo parametro è un puntatore NULL quando il valore MIB_NOTIFICATION_TYPE passato al parametro NotificationType alla funzione di callback è impostato su MibInitialNotification. Ciò può verificarsi solo se il parametro InitialNotification passato a NotifyRouteChange2 è stato impostato su TRUE durante la registrazione delle notifiche.
IN MIB_NOTIFICATION_TYPE NotificationType	Tipo di notifica. Questo membro può essere uno dei valori del tipo di enumerazione MIB_NOTIFICATION_TYPE definito nel file di intestazione Netioapi.h .

La funzione di callback specificata nel parametro Callback deve essere implementata nello stesso processo dell'applicazione che chiama la funzione NotifyRouteChange2 . Se la funzione di callback si trova in una DLL separata, la DLL deve essere caricata prima di chiamare la funzione NotifyRouteChange2 per registrare le notifiche di modifica.

Quando la funzione di callback viene ricevuta quando si verifica una modifica e il parametro Row non è NULL, il puntatore alla struttura MIB_IPFORWARD_ROW2 passata nel parametro Row contiene dati incompleti. Le informazioni restituite nella struttura MIB_IPFORWARD_ROW2 sono solo informazioni sufficienti che un'applicazione può chiamare la funzione GetIpForwardEntry2 per eseguire query sulle informazioni complete sulla route IP modificata. Quando viene ricevuta la funzione di callback, un'applicazione deve allocare una struttura MIB_IPFORWARD_ROW2 e inizializzarla con i membri DestinationPrefix, NextHop, InterfaceLuid e InterfaceIndex nella struttura MIB_IPFORWARD_ROW2 puntata dal parametro Row ricevuto. Un puntatore a questa struttura di MIB_IPFORWARD_ROW2 appena inizializzata deve essere passata alla funzione GetIpForwardEntry2 per recuperare informazioni complete sulla route IP modificata.

La memoria a cui fa riferimento il parametro Row usato nelle indicazioni di callback viene gestita dal sistema operativo. Un'applicazione che riceve una notifica non deve mai tentare di liberare la memoria puntata dal parametro Row .

Dopo aver chiamato la funzione NotifyRouteChange2 per la registrazione per le notifiche di modifica, queste notifiche continueranno a essere inviate fino a quando l'applicazione non deregisters per le notifiche di modifica o l'applicazione termina. Se l'applicazione termina, il sistema deregiregistrerà automaticamente qualsiasi registrazione per le notifiche di modifica. È comunque consigliabile che un'applicazione deregisteri in modo esplicito per le notifiche di modifica prima che venga terminata.

Qualsiasi registrazione per le notifiche di modifica non persiste se il sistema è arrestato o riavviato.

Per annullare la registrazione per le notifiche di modifica, chiamare la funzione CancelMibChangeNotify2 passando il parametro NotificationHandle restituito da NotifyRouteChange2.

Un'applicazione non può effettuare una chiamata alla funzione CancelMibChangeNotify2 dal contesto del thread che sta attualmente eseguendo la funzione di callback di notifica per lo stesso parametro NotificationHandle . In caso contrario, il thread che esegue tale callback comporterà il deadlock. Pertanto la funzione CancelMibChangeNotify2 non deve essere chiamata direttamente come parte della routine di callback di notifica. In una situazione più generale, un thread che esegue la funzione CancelMibChangeNotify2 non può essere proprietaria di una risorsa in cui il thread che esegue un'operazione di callback di notifica attenderebbe perché comporta un deadlock simile. La funzione CancelMibChangeNotify2 deve essere chiamata da un thread diverso, in cui il thread che riceve il callback di notifica non ha dipendenze.

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	netioapi.h (includere Iphlpapi.h)
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll