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.

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

Vedi anche

CreateIpForwardEntry

DeleteIpForwardEntry

GetIpForwardTable

GetIpInterfaceEntry

Informazioni di riferimento sulle funzioni helper IP

Pagina iniziale dell'helper IP

MIB_IPFORWARDROW

MIB_IPINTERFACE_ROW