Funzione NotifyIpInterfaceChange (netioapi.h)

Articolo
03/15/2023

La funzione NotifyIpInterfaceChange registra le modifiche a tutte le interfacce IP, le interfacce IPv4 o IPv6 in un computer locale.

Sintassi

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyIpInterfaceChange(
  [in]      ADDRESS_FAMILY               Family,
  [in]      PIPINTERFACE_CHANGE_CALLBACK Callback,
  [in]      PVOID                        CallerContext,
  [in]      BOOLEAN                      InitialNotification,
  [in, out] HANDLE                       *NotificationHandle
);

Parametri

[in] Family

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.

Nella Windows SDK rilasciata 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_UNSPEC 0	La famiglia di indirizzi non è specificata. Quando questo parametro viene specificato, questa funzione registra sia per le notifiche di modifica IPv4 che IPv6.
AF_INET 2	Famiglia di indirizzi Internet Protocol versione 4 (IPv4). Quando questo parametro viene specificato, questa funzione registra solo le notifiche di modifica IPv4.
AF_INET6 23	Famiglia di indirizzi IPv6 (Internet Protocol 6). Quando questo parametro viene specificato, questa funzione registra solo le notifiche di modifica IPv6.

[in] Callback

Puntatore alla funzione da chiamare quando si verifica una modifica. Questa funzione verrà richiamata quando viene ricevuta una notifica dell'interfaccia.

[in] CallerContext

Contesto utente passato alla funzione di callback specificata nel parametro Callback quando viene ricevuta una notifica dell'interfaccia.

[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 che si è verificata una modifica a un'interfaccia 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 NotifyIpInterfaceChange è 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 NotifyIpInterfaceChange durante la registrazione delle notifiche.
IN PMIB_IPINTERFACE_ROW Riga FACOLTATIVA	Puntatore alla voce MIB_IPINTERFACE_ROW per l'interfaccia 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 NotifyIpInterfaceChange è 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 NotifyIpInterfaceChange . Se la funzione di callback si trova in una DLL separata, la DLL deve essere caricata prima di chiamare la funzione NotifyIpInterfaceChange 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_IPINTERFACE_ROW passata nel parametro Row contiene dati incompleti. Le informazioni restituite nella struttura MIB_IPINTERFACE_ROW sono solo informazioni sufficienti che un'applicazione può chiamare la funzione GetIpInterfaceEntry per eseguire query sulle informazioni complete sull'interfaccia IP modificata. Quando viene ricevuta la funzione di callback, un'applicazione deve allocare una struttura MIB_IPINTERFACE_ROW e inizializzarla con i membri Family, InterfaceLuid e InterfaceIndex nella struttura MIB_IPINTERFACE_ROW puntata dal parametro Row ricevuto. Un puntatore a questa struttura di MIB_IPINTERFACE_ROW appena inizializzata deve essere passata alla funzione GetIpInterfaceEntry per recuperare informazioni complete sull'interfaccia 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 .

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

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.

Dopo aver chiamato la funzione NotifyIpInterfaceChange per la registrazione per le notifiche di modifica, queste notifiche continueranno a essere inviate fino a quando l'applicazione non deregista 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 in un sistema arrestato o riavviato.

Requisiti

Requisito	Valore
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