Funzione SetIpForwardEntry (iphlpapi.h)
La funzione SetIpForwardEntry modifica una route esistente nella tabella di routing IPv4 del computer locale.
Sintassi
IPHLPAPI_DLL_LINKAGE DWORD SetIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parametri
[in] pRoute
Puntatore a una struttura MIB_IPFORWARDROW che specifica le nuove informazioni per la route esistente. Il chiamante deve specificare MIB_IPPROTO_NETMGMT per il membro dwForwardProto di questa struttura. Il chiamante deve inoltre specificare valori per i membri dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop e dwForwardPolicy della struttura.
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 |
|---|---|
|
Accesso negato. Questo errore viene restituito in Windows Vista e Windows Server 2008 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). |
|
Non è possibile trovare il file specificato. Questo errore viene restituito in Windows Vista e versioni successive se non è stato possibile trovare l'interfaccia di rete specificata dal membro dwForwardIfIndex della struttura MIB_IPFORWARDROW a cui punta il parametro pRoute . |
|
Il parametro pRoute è NULL oppure SetIpForwardEntry non è in grado di leggere dalla memoria a cui punta pRoute oppure uno dei membri della struttura MIB_IPFORWARDROW non è valido. |
|
L'elemento non viene trovato. L'errore viene restituito in Windows Vista e versioni successive quando la funzione DeleteIpForwardEntry e quindi la funzione SetIpForwardEntry vengono chiamate per la stessa voce della tabella di route IPv4. |
|
La richiesta non è supportata. Questo valore viene restituito se il trasporto IPv4 non è configurato nel computer locale. Questo errore viene restituito anche in Windows Server 2003 e versioni precedenti se non è configurato alcun stack TCP/IP nel computer locale. |
|
Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito. |
Commenti
Il membro dwForwardProto della struttura MIB_IPFORWARDROW a cui punta il parametro di route deve essere impostato su MIB_IPPROTO_NETMGMT altrimentiSetIpForwardEntry avrà esito negativo. Gli identificatori del protocollo di routing vengono usati per identificare le informazioni di route per il protocollo di routing specificato. Ad esempio, MIB_IPPROTO_NETMGMT viene usato per identificare le informazioni di route per il routing IP impostato tramite la gestione di rete, ad esempio il protocollo DHCP (Dynamic Host Configuration Protocol), simple network management protocol (SNMP) o tramite chiamate alle funzioni CreateIpForwardEntry, DeleteIpForwardEntry o SetIpForwardEntry .
In Windows Vista e Windows Server 2008 la metrica di route specificata nel membro dwForwardMetric1 della struttura MIB_IPFORWARDROW a cui punta il parametro pRoute rappresenta una combinazione della metrica di route aggiunta alla metrica di interfaccia specificata nel membro Metric della struttura MIB_IPINTERFACE_ROW dell'interfaccia associata. Pertanto, il membro dwForwardMetric1 della struttura MIB_IPFORWARDROW deve essere uguale o maggiore del membro Metrico della struttura MIB_IPINTERFACE_ROW associata. Se un'applicazione vuole impostare la metrica di route su 0, il membro dwForwardMetric1 della struttura MIB_IPFORWARDROW deve essere impostato su uguale al valore della metrica di interfaccia specificata nel membro Metrica della struttura di MIB_IPINTERFACE_ROW associata. Un'applicazione può recuperare la metrica dell'interfaccia chiamando la funzione GetIpInterfaceEntry .
In Windows Vista e Windows Server 2008, la funzione SetIpForwardEntry funziona solo su interfacce con una singola interfaccia secondaria (in cui l'interfaccia LUID e il sottointerfaccia LUID sono gli stessi). Il membro dwForwardIfIndex della struttura MIB_IPFORWARDROW specifica l'interfaccia.
Il membro dwForwardAge la struttura MIB_IPFORWARDROW a cui punta il parametro di route non è attualmente utilizzata da SetIpForwardEntry. Il membro dwForwardAge viene usato solo se il servizio routing e accesso remoto (RRAS) è in esecuzione e quindi solo per le route di tipo MIB_IPPROTO_NETMGMT come definito nella pagina di riferimento identificatori protocollo . Quando dwForwardAge è impostato su INFINITE, la route non verrà rimossa in base a un timeout
Valore. Qualsiasi altro valore per dwForwardAge specifica il numero di secondi fino a quando lo stack TCP/IP rimuoverà la route dalla tabella di routing di rete.
Una route modificata da SetIpForwardEntry avrà automaticamente un valore predefinito per dwForwardAge di INFINITE.
Un numero di membri della struttura MIB_IPFORWARDROW a cui punta il parametro di route non è attualmente utilizzato da SetIpForwardEntry. Questi membri includono dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 e dwForwardMetric5.
Per creare una nuova route nella tabella di routing IP, usare la funzione CreateIpForwardEntry . Per recuperare la tabella di routing IP, chiamare la funzione GetIpForwardTable .
In Windows Vista e versioni successive la funzione SetIpForwardEntry può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se SetIpForwardEntry viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata di funzione avrà esito negativo e ERROR_ACCESS_DENIED viene restituito.
Questa funzione può anche non riuscire 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.
Esempio
Nell'esempio seguente viene illustrato come modificare il gateway predefinito in NewGateway. È sufficiente chiamare GetIpForwardTable, modificare il gateway e quindi chiamare SetIpForwardEntry non modificherà la route, ma aggiungerà semplicemente una nuova. Se per qualche motivo sono presenti più gateway predefiniti, questo codice li eliminerà. Si noti che il nuovo gateway deve essere valido; in caso contrario, TCP/IP ignorerà la modifica.
Windows Vista e versioni successive: Quando la funzione DeleteIpForwardEntry e la funzione SetIpForwardEntry vengono chiamate per la stessa voce della tabella di route in Windows Vista e versioni successive, viene restituita ERROR_NOT_FOUND. Il modo corretto per replicare questo esempio in Windows Vista e versioni successive consiste nell'usare la funzione CreateIpForwardEntry per creare la nuova voce della tabella di route e quindi eliminare la voce precedente della tabella di route chiamando la funzione DeleteIpForwardEntry .
#pragma comment(lib, "IPHLPAPI.lib")
// #ifndef WIN32_LEAN_AND_MEAN
// #define WIN32_LEAN_AND_MEAN
// #endif
// #pragma warning(push)
// #pragma warning(disable: 4127)
// #include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>
#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */
int main()
{
// Declare and initialize variables.
/* variables used for SetIfForwardEntry */
PMIB_IPFORWARDTABLE pIpForwardTable = NULL;
PMIB_IPFORWARDROW pRow = NULL;
DWORD dwSize = 0;
BOOL bOrder = FALSE;
DWORD dwStatus = 0;
DWORD NewGateway = 0xDDBBCCAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
DWORD i;
// Find out how big our buffer needs to be.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
// Allocate the memory for the table
pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize);
if (pIpForwardTable == NULL) {
printf("Unable to allocate memory for the IPFORWARDTALE\n");
exit(1);
}
// Now get the table.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
}
if (dwStatus != ERROR_SUCCESS) {
printf("getIpForwardTable failed.\n");
if (pIpForwardTable)
free(pIpForwardTable);
exit(1);
}
// Search for the row in the table we want. The default gateway has a destination
// of 0.0.0.0. Notice that we continue looking through the table, but copy only
// one row. This is so that if there happen to be multiple default gateways, we can
// be sure to delete them all.
for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
if (pIpForwardTable->table[i].dwForwardDest == 0) {
// We have found the default gateway.
if (!pRow) {
// Allocate some memory to store the row in. This is easier than filling
// in the row structure ourselves, and we can be sure to change only the
// gateway address.
pRow = (PMIB_IPFORWARDROW) malloc(sizeof (MIB_IPFORWARDROW));
if (!pRow) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Copy the row.
memcpy(pRow, &(pIpForwardTable->table[i]),
sizeof (MIB_IPFORWARDROW));
}
// Delete the old default gateway entry.
dwStatus = DeleteIpForwardEntry(&(pIpForwardTable->table[i]));
if (dwStatus != ERROR_SUCCESS) {
printf("Could not delete old gateway\n");
exit(1);
}
}
}
// Set the nexthop field to our new gateway. All the other properties of the route will
// be the same as they were previously.
pRow->dwForwardNextHop = NewGateway;
// Create a new route entry for the default gateway.
dwStatus = SetIpForwardEntry(pRow);
if (dwStatus == NO_ERROR)
printf("Gateway changed successfully\n");
else if (dwStatus == ERROR_INVALID_PARAMETER)
printf("Invalid parameter.\n");
else
printf("Error: %d\n", dwStatus);
// Free resources.
if (pIpForwardTable)
free(pIpForwardTable);
if (pRow)
free(pRow);
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | iphlpapi.h |
| Libreria | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
Vedi anche
Informazioni di riferimento sulle funzioni helper IP
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per