Funzione NotifyStableUnicastIpAddressTable (netioapi.h)

Articolo
03/15/2023

La funzione NotifyStableUnicastIpAddressTable recupera la tabella degli indirizzi IP unicast stabile in un computer locale.

Sintassi

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [in, out] HANDLE                                   *NotificationHandle
);

Parametri

[in] Family

Famiglia di indirizzi da recuperare.

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_UNSPEC 0	La famiglia di indirizzi non è specificata. Quando si specifica questo parametro, la funzione recupera la tabella di indirizzi IP unicast stabile contenente sia le voci IPv4 che IPv6.
AF_INET 2	Famiglia di indirizzi IPv4 (Internet Protocol versione 4). Quando questo parametro viene specificato, la funzione recupera la tabella di indirizzi IP unicast stabile contenente solo le voci IPv4.
AF_INET6 23	Famiglia di indirizzi IPv6 (Internet Protocol versione 6). Quando questo parametro viene specificato, la funzione recupera la tabella di indirizzi IP unicast stabile contenente solo voci IPv6.

[in, out] Table

Puntatore a una struttura MIB_UNICASTIPADDRESS_TABLE . Quando NotifyStableUnicastIpAddressTable ha esito positivo, questo parametro restituisce la tabella degli indirizzi IP unicast stabile nel computer locale.

Quando NotifyStableUnicastIpAddressTable restituisce ERROR_IO_PENDING che indica che la richiesta di I/O è in sospeso, la tabella degli indirizzi IP unicast stabile viene restituita alla funzione nel parametro CallerCallback .

[in] CallerCallback

Puntatore alla funzione da chiamare con la tabella degli indirizzi IP unicast stabile. Questa funzione verrà richiamata se NotifyStableUnicastIpAddressTable restituisce ERROR_IO_PENDING, a indicare che la richiesta di I/O è in sospeso.

[in] CallerContext

Contesto utente passato alla funzione di callback specificata nel parametro CallerCallback quando è disponibile la tabella degli indirizzi IP unicast stabile.

[in, out] NotificationHandle

Puntatore utilizzato per restituire un handle che può essere usato per annullare la richiesta per recuperare la tabella degli indirizzi IP unicast stabile. Questo parametro viene restituito se il valore restituito da NotifyStableUnicastIpAddressTable è ERROR_IO_PENDING che indica che la richiesta di I/O è in sospeso.

Valore restituito

Se la funzione ha esito positivo immediatamente, il valore restituito è NO_ERROR e la tabella IP unicast stabile viene restituita nel parametro Table .

Se la richiesta di I/O è in sospeso, la funzione restituisce ERROR_IO_PENDING e la funzione a cui punta il parametro CallerCallback viene chiamata quando la richiesta di I/O è stata completata con la tabella degli indirizzi IP unicast stabile.

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 Table è un puntatore NULL , il parametro NotificationHandle è un puntatore NULL oppure 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 NotifyStableUnicastIpAddressTable viene definita in Windows Vista e versioni successive.

Se la funzione NotifyStableUnicastIpAddressTable ha esito positivo immediatamente, il valore restituito è NO_ERROR e la tabella IP unicast stabile viene restituita nel parametro Table . L'applicazione chiamante deve liberare la memoria a cui punta il parametro Table usando la funzione FreeMibTable quando le informazioni MIB_UNICASTIPADDRESS_TABLE non sono più necessarie.

Tutti gli indirizzi IP unicast ad eccezione degli indirizzi dial-on-demand vengono considerati stabili solo se sono nello stato preferito. Per una normale voce di indirizzo IP unicast, corrisponde a un membro DadState del MIB_UNICASTIPADDRESS_ROW per l'indirizzo IP impostato su IpDadStatePreferred. Ogni indirizzo dial-on-demand definisce la propria metrica di stabilità. Attualmente l'unico indirizzo su richiesta considerato da questa funzione è l'indirizzo IP unicast usato dal client Teredo nel computer locale.

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

Quando NotifyStableUnicastIpAddressTable ha esito positivo e restituisce NO_ERROR, il parametro Table restituisce la tabella degli indirizzi IP unicast stabile nel computer locale.

La funzione NotifyStableUnicastIpAddressTable viene usata principalmente dalle applicazioni che usano il client Teredo.

Se l'indirizzo IP unicast usato da Teredo è disponibile nel computer locale ma non nello stato stabile (qualificato), NotifyStableUnicastIpAddressTable restituisce ERROR_IO_PENDING e la tabella degli indirizzi IP unicast stabile viene restituita chiamando la funzione nel parametro CallerCallback. Se l'indirizzo Teredo non è disponibile o è nello stato stabile e gli altri indirizzi IP unicast si trovano in uno stato stabile, la funzione nel parametro CallerCallback non verrà mai richiamata.

La funzione di callback specificata nel parametro CallerCallback 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 NotifyStableUnicastIpAddressTable durante la registrazione per le notifiche.
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable	Puntatore a un MIB_UNICASTIPADDRESS_TABLE contenente la tabella degli indirizzi IP unicast stabile nel computer locale.

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

La memoria a cui punta il parametro AddressTable utilizzato in un'indicazione di callback viene allocata dal sistema operativo. Un'applicazione che riceve una notifica deve liberare la memoria a cui punta il parametro AddressTable usando la funzione FreeMibTable quando le informazioni di MIB_UNICASTIPADDRESS_TABLE non sono più necessarie.

Quando viene chiamata la funzione NotifyStableUnicastIpAddressTable per registrarsi per le notifiche di modifica, queste notifiche continueranno a essere inviate fino a quando 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 in modo esplicito la registrazione di eventuali 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 NotifyStableUnicastIpAddressTable.

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