Funzione SetIpForwardEntry2 (netioapi.h)

Articolo
08/25/2023

La funzione SetIpForwardEntry2 imposta le proprietà di una voce di route IP nel computer locale.

Sintassi

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Route
);

Parametri

[in] Route

Puntatore a una voce di struttura MIB_IPFORWARD_ROW2 per una voce di route IP. Il membro DestinationPrefix del MIB_IPFORWARD_ROW2 deve essere impostato su un prefisso di destinazione IP valido, il membro NextHop del MIB_IPFORWARD_ROW2 deve essere impostato su una famiglia di indirizzi IP e un indirizzo IP validi e il membro InterfaceLuid o InterfaceIndex del MIB_IPFORWARD_ROW2 deve essere specificato.

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_ACCESS_DENIED	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).
ERROR_INVALID_PARAMETER	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se nel parametro Route viene passato un puntatore NULL, il membro DestinationPrefix del MIB_IPFORWARD_ROW2 a cui punta il parametro Route non è stato specificato, il membro NextHop del MIB_IPFORWARD_ROW2 a cui punta il parametro Route non è stato specificato o sia i membri InterfaceLuid o InterfaceIndex del MIB_IPFORWARD_ROW2 a cui punta la route parametro non specificato.
ERROR_NOT_FOUND	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_IPFORWARD_ROW2 a cui punta il parametro Route .
Altri	Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Commenti

La funzione SetIpForwardEntry2 viene definita in Windows Vista e versioni successive.

La funzione SetIpForwardEntry2 viene usata per impostare le proprietà per una voce di route IP esistente in un computer locale.

Il membro DestinationPrefix nella struttura MIB_IPFORWARD_ROW2 a cui punta il parametro Route deve essere inizializzato in un prefisso e una famiglia di indirizzi IP validi. Il membro NextHop nella struttura MIB_IPFORWARD_ROW2 a cui punta il parametro Route deve essere inizializzato in un indirizzo IP e una famiglia validi. Inoltre, almeno uno dei membri seguenti nella struttura MIB_IPFORWARD_ROW2 punta al parametro Route deve essere inizializzato all'interfaccia: InterfaceLuid o InterfaceIndex.

I campi vengono usati nell'ordine indicato in precedenza. Quindi, se si specifica InterfaceLuid , questo membro viene usato per determinare l'interfaccia in cui aggiungere l'indirizzo IP unicast. Se non è stato impostato alcun valore per il membro InterfaceLuid (i valori di questo membro sono stati impostati su zero), il membro InterfaceIndex viene usato successivamente per determinare l'interfaccia.

L'offset della metrica di route specificato nel membro Metric della struttura MIB_IPFORWARD_ROW2 a cui punta il parametro Route rappresenta solo parte della metrica di route completa. La metrica completa è una combinazione di questo offset della metrica di route aggiunto alla metrica di interfaccia specificata nel membro Metric della struttura MIB_IPINTERFACE_ROW dell'interfaccia associata. Un'applicazione può recuperare la metrica dell'interfaccia chiamando la funzione GetIpInterfaceEntry .

I membri Age e Origin della struttura MIB_IPFORWARD_ROW2 a cui punta row vengono ignorati quando viene chiamata la funzione SetIpForwardEntry2 . Questi membri vengono impostati dallo stack di rete e non possono essere modificati usando la funzione SetIpForwardEntry2 .

La funzione SetIpForwardEntry2 avrà esito negativo se i membri DestinationPrefix e NextHop del MIB_IPFORWARD_ROW2 a cui punta il parametro Route non corrispondono a una voce di route IP nell'interfaccia specificata.

La funzione SetIpForwardEntry2 può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se SetIpForwardEntry2 viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata di funzione avrà esito negativo e ERROR_ACCESS_DENIED viene restituito.

La funzione SetIpForwardEntry2 può avere esito negativo anche a causa del controllo dell'account utente in Windows Vista e versioni successive. Se un'applicazione che contiene 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 impostato su requireAdministrator. Se l'applicazione non dispone di questo file manifesto, un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) affinché questa funzione abbia esito positivo.

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 (include Iphlpapi.h)
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll