Funzione SetUnicastIpAddressEntry (netioapi.h)
La funzione SetUnicastIpAddressEntry imposta le proprietà di una voce di indirizzo IP unicast esistente nel computer locale.
Sintassi
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
[in] const MIB_UNICASTIPADDRESS_ROW *Row
);
Parametri
[in] Row
Puntatore a una voce di struttura MIB_UNICASTIPADDRESS_ROW per una voce di indirizzo IP unicast esistente.
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 |
|---|---|
|
Accesso negato. Questo errore viene restituito in diverse condizioni che includono quanto segue: l'utente non dispone dei privilegi amministrativi necessari nel computer locale o l'applicazione non è in esecuzione in una shell avanzata come amministratore predefinito (amministratore RunAs). |
|
Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se un puntatore NULL viene passato nel parametro Row, il membro Address del MIB_UNICASTIPADDRESS_ROW puntato al parametro Row non è stato impostato su un indirizzo IPv4 o IPv6 valido oppure entrambi i membri InterfaceLuid o InterfaceIndexMIB_UNICASTIPADDRESS_ROW del parametroRow 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 quanto segue: se il membro ValidLifetime è minore del membro PreferredLifetime, se il membro PrefixOrigin è impostato su IpPrefixOriginUnchanged e il suffissoOrigin Non è impostato su IpSuffixOriginUnchanged, se il membro PrefixOrigin non è impostato su IpPrefixOriginUnchanged e su SuffixOriginOrigin è impostato su IpSuffixOriginUnchanged, se il prefixOriginUnchanged membro non è impostato su un valore dall'enumerazione NL_PREFIX_ORIGIN, se il membro SuffixOrigin non è impostato su un valore dall'enumerazione NL_SUFFIX_ORIGIN o se 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). |
|
Impossibile trovare l'interfaccia specificata. Questo errore viene restituito se non è stato possibile trovare l'interfaccia di rete specificata dal membro InterfaceLuid o InterfaceIndex del MIB_UNICASTIPADDRESS_ROW puntato dal parametro Row . |
|
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 AddressMIB_UNICASTIPADDRESS_ROW puntato dal parametro Row o nessun stack IPv6 si trova nel computer locale e un indirizzo IPv6 è stato specificato nel membro Address . |
|
Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito. |
Commenti
La funzione SetUnicastIpAddressEntry viene definita in Windows Vista e versioni successive.
La funzione GetUnicastIpAddressEntry viene in genere usata per recuperare una voce di struttura MIB_UNICASTIPADDRESS_ROW esistente da modificare. Un'applicazione può quindi modificare i membri nella voce MIB_UNICASTIPADDRESS_ROW che desidera modificare e quindi chiamare la funzione SetUnicastIpAddressEntry .
Un'applicazione può chiamare la funzione InitializeUnicastIpAddressEntry per inizializzare i membri di una voce di struttura MIB_UNICASTIPADDRESS_ROW con valori predefiniti prima di apportare modifiche. Tuttavia, l'applicazione salva normalmente il membro InterfaceLuid o InterfaceIndex prima di chiamare InitializeUnicastIpAddressEntry e ripristinare uno di questi membri dopo la chiamata.
Il membro Address nella struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row deve essere inizializzato in un indirizzo IPv4 o IPv6 valido. Inoltre, almeno uno dei membri seguenti nella struttura MIB_UNICASTIPADDRESS_ROW punta al parametro Row deve essere inizializzato: InterfaceLuid o InterfaceIndex.
I campi vengono usati nell'ordine elencato sopra. Quindi, se si specifica InterfaceLuid , questo membro viene usato per determinare l'interfaccia. Se non è stato impostato alcun valore per il membro InterfaceLuid (i valori di questo membro è stato impostato su zero), il membro InterfaceIndex viene usato successivamente per determinare l'interfaccia.
Se il membro OnLinkPrefixLength del MIB_UNICASTIPADDRESS_ROW indicato dal parametro Row è impostato su 255, SetUnicastIpAddressEntry imposta le proprietà dell'indirizzo IP unicast in modo che il membro OnLinkPrefixLength sia 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 ciò comporta la subnet mask errata per un indirizzo IPv4 o il prefisso di collegamento non corretto per un indirizzo IPv6, l'applicazione deve impostare questo membro sul valore corretto prima di chiamare SetUnicastIpAddressEntry.
I membri DadState, ScopeId e CreationTimeStamp della struttura MIB_UNICASTIPADDRESS_ROW puntati dalla riga vengono ignorati quando viene chiamata la funzione SetUnicastIpAddressEntry . Questi membri vengono impostati dallo stack di rete e non possono essere modificati usando la funzione SetUnicastIpAddressEntry . Il membro ScopeId viene determinato automaticamente dall'interfaccia in cui è stato aggiunto l'indirizzo.
La funzione SetUnicastIpAddressEntry può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se SetUnicastIpAddressEntry viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata alla funzione avrà esito negativo e ERROR_ACCESS_DENIED viene restituita.
La funzione SetUnicastIpAddressEntry può anche non riuscire a causa del controllo dell'account utente in Windows Vista e versioni successive. Se un'applicazione contenente questa funzione viene eseguita da un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito, questa chiamata avrà esito negativo a meno che l'applicazione non sia stata contrassegnata nel file manifesto con un set requestedExecutionLevel per richiedereAdministrator. Se l'applicazione manca di questo file manifesto, un utente ha eseguito l'accesso come membro del gruppo Administrators diverso dall'amministratore predefinito, deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) per la riuscita di questa funzione.
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 |
Vedi anche
Informazioni di riferimento sulla funzione helper IP