Funzione CreateUnicastIpAddressEntry

Articolo
05/03/2024

La funzione CreateUnicastIpAddressEntry aggiunge una nuova voce di indirizzo IP unicast nel computer locale.

Sintassi

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

Parametri

Riga [in]
Puntatore a una voce di struttura MIB_UNICASTIPADDRESS_ROW per una voce di indirizzo IP unicast.

Valore restituito

CreateUnicastIpAddressEntry restituisce STATUS_SUCCESS se la funzione ha esito positivo.

Se la funzione ha esito negativo, CreateUnicastIpAddressEntry restituisce uno dei codici di errore seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se viene passato un puntatore NULL nel parametro Row, il membro Address della struttura MIB_UNICASTIPADDRESS_ROW a cui il parametro Row punta non è stato impostato su un indirizzo IPv4 o IPv6 valido oppure i membri InterfaceLuid e InterfaceIndex della struttura MIB_UNICASTIPADDRESS_ROW non sono stati specificati. Questo errore viene restituito anche per altri errori nei valori impostati per i membri nella struttura MIB_UNICASTIPADDRESS_ROW. Questi errori includono le situazioni seguenti: Il membro ValidLifetime è minore del membro PreferredLifetime . Il membro PrefixOrigin è impostato su IpPrefixOriginUnchanged e SuffixOrigin non è impostato su IpSuffixOriginUnchanged. Il membro PrefixOrigin non è impostato su IpPrefixOriginUnchanged e SuffixOrigin è impostato su IpSuffixOriginUnchanged. Il membro PrefixOrigin non è impostato su un valore dell'enumerazione NL_PREFIX_ORIGIN . Il membro SuffixOrigin non è impostato su un valore dell'enumerazione NL_SUFFIX_ORIGIN. Il membro OnLinkPrefixLength è impostato su un valore maggiore della lunghezza dell'indirizzo IP, in bit (32 per un indirizzo IPv4 unicast o 128 per un indirizzo IPv6 unicast). Per i valori possibili delle enumerazioni NL_PREFIX_ORIGIN e NL_SUFFIX_ORIGIN, vedere MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	Impossibile trovare l'interfaccia specificata. Questo errore viene restituito se la funzione non riesce a trovare l'interfaccia di rete specificata dal membro InterfaceLuid o InterfaceIndex della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row .
STATUS_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se non si trova alcun stack IPv4 nel computer locale e un indirizzo IPv4 è stato specificato nel membro Address della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row oppure se non si trova alcun stack IPv6 nel computer locale e nel membro Address è stato specificato un indirizzo IPv6.
ERROR_OBJECT_ALREADY_EXISTS	L'oggetto esiste già. Questo errore viene restituito se il membro Address della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row è un duplicato di un indirizzo IP unicast esistente nell'interfaccia specificata dal membro InterfaceLuid o InterfaceIndex del MIB_UNICASTIPADDRESS_ROW.
Altro	Utilizzare la funzione FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Osservazioni:

Utilizzare la funzione InitializeUnicastIpAddressEntry per inizializzare i membri di una voce di struttura MIB_UNICASTIPADDRESS_ROW con valori predefiniti. Un driver può quindi modificare i membri nella voce MIB_UNICASTIPADDRESS_ROW che vuole modificare e quindi chiamare la funzione CreateUnicastIpAddressEntry .

All'input, il driver deve inizializzare i membri seguenti della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row .

Indirizzo
Impostare su un indirizzo e una famiglia IPv4 o IPv6 unicast validi.
InterfaceLuid o InterfaceIndex
Questi membri vengono utilizzati nell'ordine elencato in precedenza. Pertanto, se si specifica InterfaceLuid , questo membro viene usato per determinare l'interfaccia a cui aggiungere l'indirizzo IP unicast. Se non è stato impostato alcun valore per il membro InterfaceLuid (il valore di questo membro è stato impostato su zero), il membro InterfaceIndex viene usato successivamente per determinare l'interfaccia.

Se il membro OnLinkPrefixLength della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row è impostato su 255, CreateUnicastIpAddressEntry aggiunge il nuovo indirizzo IP unicast con il membro OnLinkPrefixLength impostato uguale alla lunghezza dell'indirizzo IP. Pertanto, per un indirizzo IPv4 unicast, OnLinkPrefixLength è impostato su 32 e OnLinkPrefixLength è impostato su 128 per un indirizzo IPv6 unicast. Se questa impostazione genera la subnet mask non corretta per un indirizzo IPv4 o il prefisso di collegamento non corretto per un indirizzo IPv6, il driver deve impostare il membro OnLinkPrefixLength sul valore corretto prima di chiamare CreateUnicastIpAddressEntry.

Se viene creato un indirizzo IP unicast con il membro OnLinkPrefixLength impostato in modo non corretto, il driver può modificare l'indirizzo IP chiamando SetUnicastIpAddressEntry con il membro OnLinkPrefixLength impostato sul valore corretto.

I membri DadState, ScopeId e CreationTimeStamp della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row vengono ignorati quando viene chiamata la funzione CreateUnicastIpAddressEntry . Questi membri vengono impostati dallo stack di rete. Il membro ScopeId viene determinato automaticamente dall'interfaccia su cui viene aggiunto l'indirizzo.

La funzione CreateUnicastIpAddressEntry ha esito negativo se l'indirizzo IP unicast passato nel membro Address della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row è un duplicato di un indirizzo IP unicast esistente nell'interfaccia. Si noti che il driver può aggiungere un indirizzo IP di loopback a un'interfaccia di loopback solo usando la funzione CreateUnicastIpAddressEntry .

L'indirizzo IP unicast passato nel membro Address della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row non è immediatamente utilizzabile. L'indirizzo IP è utilizzabile dopo che il processo di rilevamento degli indirizzi duplicati è stato completato correttamente. Il completamento del processo di rilevamento degli indirizzi duplicati può richiedere alcuni secondi perché è necessario inviare pacchetti IP e attendere potenziali risposte. Per IPv6, il processo di rilevamento degli indirizzi duplicati richiede in genere circa 1 secondo. Per IPv4, il processo di rilevamento degli indirizzi duplicati richiede in genere circa 3 secondi.

Dopo che un driver chiama la funzione CreateUnicastIpAddressEntry , può usare i metodi seguenti per determinare se un indirizzo IP è ancora utilizzabile:

Usare il polling e la funzione GetUnicastIpAddressEntry
Dopo che la chiamata alla funzione CreateUnicastIpAddressEntry viene restituita correttamente, sospendere per 1-3 secondi (a seconda che venga creato un indirizzo IPv6 o IPv4) per consentire il completamento corretto del processo di rilevamento degli indirizzi di duplicazione. Chiamare quindi GetUnicastIpAddressEntry per recuperare la struttura di MIB_UNICASTIPADDRESS_ROW aggiornata ed esaminare il valore del membro DadState . Se il valore del membro DadState è impostato su IpDadStatePreferred, l'indirizzo IP è ora utilizzabile. Se il valore del membro DadState è impostato su IpDadStateTentative, il rilevamento degli indirizzi duplicati non è ancora stato completato. In questo caso, chiamare di nuovo la funzione GetUnicastIpAddressEntry ogni 0,5 secondi mentre il membro DadState è ancora impostato su IpDadStateTentative. Se il valore del membro DadState restituisce un valore diverso da IpDadStatePreferred o IpDadStateTentative, il rilevamento degli indirizzi duplicati non è riuscito e l'indirizzo IP non è utilizzabile.
Chiamare una delle funzioni di notifica NotifyXxx dell'helper IP per configurare una notifica asincrona per quando un indirizzo cambia
Dopo che la chiamata alla funzione CreateUnicastIpAddressEntry viene restituita correttamente, chiamare la funzione NotifyUnicastIpAddressChange per registrare il driver per ricevere una notifica delle modifiche apportate agli indirizzi IP unicast IPv6 o IPv4, a seconda del tipo di indirizzo IP creato. Quando viene ricevuta una notifica per l'indirizzo IP creato, chiamare la funzione GetUnicastIpAddressEntry per recuperare il membro DadState . Se il valore del membro DadState è impostato su IpDadStatePreferred, l'indirizzo IP è ora utilizzabile. Se il valore del membro DadState è impostato su IpDadStateTentative, il rilevamento degli indirizzi duplicati non è ancora stato completato e il driver deve attendere le notifiche future. Se il valore del membro DadState restituisce un valore diverso da IpDadStatePreferred o IpDadStateTentative, il rilevamento degli indirizzi duplicati non è riuscito e l'indirizzo IP non è utilizzabile.

Se, durante il processo di rilevamento degli indirizzi duplicati, il supporto viene disconnesso e quindi riconnesso, il processo di rilevamento degli indirizzi duplicati viene riavviato. Il tempo necessario per completare il processo potrebbe quindi aumentare oltre il valore tipico di 1 secondo per IPv6 o 3 secondi per IPv4.

Requisiti

Piattaforma di destinazione	Universale
Versione	Disponibile in Windows Vista e versioni successive dei sistemi operativi Windows.
Intestazione	Netioapi.h (include Netioapi.h)
Libreria	Netio.lib
IRQL	< DISPATCH_LEVEL