Funzione DeleteIpForwardEntry (iphlpapi.h)

La funzione DeleteIpForwardEntry elimina una route esistente nella tabella di routing IPv4 del computer locale.

Sintassi

IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Parametri

[in] pRoute

Puntatore a una struttura MIB_IPFORWARDROW . Questa struttura specifica informazioni che identificano la route da eliminare. Il chiamante deve specificare i valori per i membri dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop e dwForwardProto della struttura.

Valore restituito

La funzione restituisce NO_ERROR (zero) se la routine ha esito positivo.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Se la funzione ha esito negativo, usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

Il membro dwForwardProto del puntatore della struttura MIB_IPFORWARDROW su per il parametro di route deve essere impostato su MIB_IPPROTO_NETMGMT altrimenti DeleteIpForwardEntry 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), il Simple Network Management Protocol (SNMP) o le chiamate alle funzioni CreateIpForwardEntry, DeleteIpForwardEntry o SetIpForwardEntry.

In Windows Vista e Windows Server 2008, DeleteIpForwardEntry funziona solo su interfacce con una singola interfaccia secondaria (dove l'interfaccia LUID e il sottointerfaceNTE LUID sono gli stessi). Il membro dwForwardIfIndex della struttura MIB_IPFORWARDROW specifica l'interfaccia.

Un numero di membri della struttura MIB_IPFORWARDROW a cui punta il parametro di route non è attualmente usato da CreateIpForwardEntry. Questi membri includono dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 e dwForwardMetric5.

Per modificare una route esistente nella tabella di routing IPv4, usare la funzione SetIpForwardEntry . Per recuperare la tabella di routing IPv4, chiamare la funzione GetIpForwardTable .

In Windows Vista e versioni successive, la funzione DeleteIpForwardEntry può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se DeleteIpForwardEntry 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 DeleteIpForwardEntry 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.

Esempio

Nell'esempio di codice seguente viene illustrato come modificare il gateway predefinito in NewGateway. Chiamando GetIpForwardTable, modificando il gateway e chiamando SetIpForwardEntry non cambierà la route, ma aggiungerà una nuova. Se esistono più gateway predefiniti, questo codice li eliminerà. Tenere presente che il nuovo gateway deve essere valido; in caso contrario, TCP/IP ignora la modifica.

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <windows.h>
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

#pragma comment(lib, "iphlpapi.lib")

int main()
{
    // Declare and initialize variables
    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

    unsigned int i;

// Identify the required size of the buffer.
    dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
        // Allocate memory for the table.
        if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
            printf("Malloc failed. Out of memory.\n");
            exit(1);
        }
        // Retrieve the table.
        dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    }

    if (dwStatus != ERROR_SUCCESS) {
        printf("getIpForwardTable failed.\n");
        if (pIpForwardTable)
            free(pIpForwardTable);
        exit(1);
    }
// Search for the required row in the table. The default gateway has a destination
// of 0.0.0.0. Be aware the table continues to be searched, but only
// one row is copied. This is to ensure that, if multiple gateways exist, all of them are deleted.
// 
    for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
        if (pIpForwardTable->table[i].dwForwardDest == 0) {
            // The default gateway was found.
            if (!pRow) {
                // Allocate memory to store the row. This is easier than manually filling
                // the row structure; only the gateway address is changed.
                //
                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 other properties of the route will
// remain the same.
    pRow->dwForwardNextHop = NewGateway;

// Create a new route entry for the default gateway.
    dwStatus = CreateIpForwardEntry(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 the memory. 
    if (pIpForwardTable)
        free(pIpForwardTable);
    if (pRow)
        free(pRow);

    exit(0);
}

Requisiti

Vedi anche

CreateIpForwardEntry

FormatMessage

GetIpForwardTable

Informazioni di riferimento sulla funzione helper IP

Pagina iniziale dell'helper IP

MIB_IPFORWARDROW

SetIpForwardEntry