Funzione NotifyUnicastIpAddressChange (netioapi.h)

Articolo
02/29/2024

La funzione NotifyUnicastIpAddressChange deve ricevere una notifica per le modifiche a tutte le interfacce IP unicast, gli indirizzi IPv4 unicast o gli indirizzi IPv6 unicast in un computer locale.

Sintassi

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

Parametri

[in] Family

Famiglia di indirizzi in cui registrarsi per 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 PF_ sono identiche (ad esempio, AF_INET e PF_INET), in modo che sia possibile usare entrambe le costanti.

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 sono definiti nel file di intestazione Ws2def.h. Si noti che il file di intestazione Ws2def.h viene automaticamente incluso 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	Registrarsi solo per le notifiche di modifica dell'indirizzo IPv4 unicast.
AF_INET6	Registrarsi solo per le notifiche di modifica dell'indirizzo IPv6 unicast.
AF_UNSPEC	Eseguire la registrazione per le notifiche di modifica dell'indirizzo IPv4 e IPv6 unicast.

[in] Callback

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

[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 di modifica. Questa notifica iniziale non indica che si è verificata una modifica a un indirizzo IP unicast. Scopo di questo parametro per fornire la conferma della registrazione del callback.

[in, out] NotificationHandle

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

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene 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	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se il parametro Family non è stato AF_INET, AF_INET6 o AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente.
Altri	Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Commenti

La funzione NotifyUnicastIpAddressChange 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 di callback includono quanto segue:

Parametro	Descrizione
IN PVOID CallerContext	Il parametro CallerContext passato alla funzione NotifyUnicastIpAddressChange durante la registrazione per le notifiche.
IN PMIB_UNICASTIPADDRESS_ROW Riga FACOLTATIVA	Puntatore alla voce MIB_UNICASTIPADDRESS_ROW per l'indirizzo IP unicast modificato. Questo parametro è un puntatore NULL quando il valore MIB_NOTIFICATION_TYPE passato nel parametro NotificationType alla funzione di callback è impostato su MibInitialNotification. Questa situazione può verificarsi solo se il parametro InitialNotification passato a NotifyUnicastIpAddressChange è stato impostato su TRUE durante la registrazione per le 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 NotifyUnicastIpAddressChange . Se la funzione di callback si trova in una DLL separata, la DLL deve essere caricata prima di chiamare la funzione NotifyUnicastIpAddressChange per eseguire la registrazione per le notifiche di modifica.

Quando si riceve la funzione di callback quando si verifica una modifica e il parametro Row non è NULL, il puntatore alla struttura MIB_UNICASTIPADDRESS_ROW passata nel parametro Row contiene dati incompleti. Le informazioni restituite nella struttura MIB_UNICASTIPADDRESS_ROW sono solo informazioni sufficienti che un'applicazione può chiamare la funzione GetUnicastIpAddressEntry per eseguire query sulle informazioni complete sull'indirizzo IP modificato. Quando viene ricevuta la funzione di callback, un'applicazione deve allocare una struttura MIB_UNICASTIPADDRESS_ROW e inizializzarla con i membri Address, InterfaceLuid e InterfaceIndex nella struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row ricevuto. Un puntatore a questa struttura di MIB_UNICASTIPADDRESS_ROW appena inizializzata deve essere passato alla funzione GetUnicastIpAddressEntry per recuperare informazioni complete sull'indirizzo IP unicast modificato.

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

Dopo che la funzione NotifyUnicastIpAddressChange viene chiamata per la registrazione per le notifiche di modifica, queste notifiche continueranno a essere inviate finché l'applicazione non viene annullata la registrazione per le notifiche di modifica o l'applicazione termina. Se l'applicazione termina, il sistema annulla automaticamente la registrazione per le notifiche di modifica. È comunque consigliabile annullare la registrazione esplicita di un'applicazione per le notifiche di modifica prima che termini.

Qualsiasi registrazione per le notifiche di modifica non viene mantenuta se il sistema viene arrestato o riavviato.

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

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 il callback genererà un 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 proprietario di una risorsa in cui il thread che esegue un'operazione di callback di notifica attenderebbe perché genera 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

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	netioapi.h (include Iphlpapi.h)
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll