SetIpForwardEntry-Funktion (iphlpapi.h)

Artikel
08/24/2023

Die SetIpForwardEntry-Funktion ändert eine vorhandene Route in der IPv4-Routingtabelle des lokalen Computers.

Syntax

IPHLPAPI_DLL_LINKAGE DWORD SetIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Parameter

[in] pRoute

Ein Zeiger auf eine MIB_IPFORWARDROW-Struktur , die die neuen Informationen für die vorhandene Route angibt. Der Aufrufer muss MIB_IPPROTO_NETMGMT für den dwForwardProto-Member dieser Struktur angeben. Der Aufrufer muss auch Werte für die Elemente dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop und dwForwardPolicy der Struktur angeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Zugriff verweigert.“ Dieser Fehler wird unter Windows Vista und Windows Server 2008 unter folgenden Bedingungen zurückgegeben: Dem Benutzer fehlen die erforderlichen Administratorrechte auf dem lokalen Computer, oder die Anwendung wird nicht in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausgeführt.
ERROR_FILE_NOT_FOUND	Die angegebene Datei wurde nicht gefunden. Dieser Fehler wird unter Windows Vista und später zurückgegeben, wenn die vom dwForwardIfIndex-Member der MIB_IPFORWARDROW Struktur angegeben wurde, auf die der pRoute-Parameter verweist, nicht gefunden wurde.
ERROR_INVALID_PARAMETER	Der pRoute-Parameter ist NULL, oder SetIpForwardEntry kann nicht aus dem Speicher lesen, auf den pRoute verweist, oder eines der Member der MIB_IPFORWARDROW-Struktur ist ungültig.
ERROR_NOT_FOUND	Das Element wurde nicht gefunden. Der Fehler wird unter Windows Vista und später zurückgegeben, wenn die DeleteIpForwardEntry-Funktion und dann die SetIpForwardEntry-Funktion für den gleichen IPv4-Routingtabelleneintrag aufgerufen werden.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Wert wird zurückgegeben, wenn der IPv4-Transport nicht auf dem lokalen Computer konfiguriert ist. Dieser Fehler wird auch unter Windows Server 2003 und früher zurückgegeben, wenn auf dem lokalen Computer kein TCP/IP-Stapel konfiguriert ist.
Andere	Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Das dwForwardProto-ElementMIB_IPFORWARDROW Struktur , auf die der routenparameter verweist, muss auf MIB_IPPROTO_NETMGMT festgelegt werden , andernfalls schlägt SetIpForwardEntry fehl. Routingprotokollbezeichner werden verwendet, um Routeninformationen für das angegebene Routingprotokoll zu identifizieren. Beispielsweise wird MIB_IPPROTO_NETMGMT verwendet, um Routeninformationen für das IP-Routing zu identifizieren, die über die Netzwerkverwaltung festgelegt werden, z. B. das Dynamic Host Configuration Protocol (DHCP), das Simple Network Management Protocol (SNMP) oder durch Aufrufe der Funktionen CreateIpForwardEntry, DeleteIpForwardEntry oder SetIpForwardEntry .

Unter Windows Vista und Windows Server 2008 stellt die Routenmetrik, die im dwForwardMetric1-Element der MIB_IPFORWARDROW-Struktur angegeben ist, auf die vom pRoute-Parameter verwiesen wird, eine Kombination der Routenmetrik dar, die der Schnittstellenmetrik hinzugefügt wird , die im Metrikelement der MIB_IPINTERFACE_ROW-Struktur der zugeordneten Schnittstelle angegeben ist. Daher sollte das dwForwardMetric1-Element der MIB_IPFORWARDROW-Struktur gleich oder größer als der Metric-Member der zugeordneten MIB_IPINTERFACE_ROW-Struktur sein. Wenn eine Anwendung die Routenmetrik auf 0 festlegen möchte, sollte der dwForwardMetric1-Member der MIB_IPFORWARDROW-Struktur gleich dem Wert der Schnittstellenmetrik festgelegt werden, der im Metrikelement der zugeordneten MIB_IPINTERFACE_ROW-Struktur angegeben ist. Eine Anwendung kann die Schnittstellenmetrik abrufen, indem sie die GetIpInterfaceEntry-Funktion aufruft .

Unter Windows Vista und Windows Server 2008 funktioniert die SetIpForwardEntry-Funktion nur auf Schnittstellen mit einer einzelnen Unterschnittstelle (wobei die Schnittstellen-LUID und die Unteroberfläche LUID identisch sind). Der dwForwardIfIndex-Member der MIB_IPFORWARDROW-Struktur gibt die -Schnittstelle an.

Das dwForwardAge-Element , auf das die MIB_IPFORWARDROW Struktur verweist, auf die der routenparameter verweist, wird derzeit nicht von SetIpForwardEntry verwendet. Der dwForwardAge-Member wird nur verwendet, wenn der Routing- und RAS-Dienst (RRAS) ausgeführt wird, und dann nur für Routen vom Typ MIB_IPPROTO_NETMGMT , wie auf der Referenzseite für Protokollbezeichner definiert. Wenn dwForwardAge auf INFINITE festgelegt ist, wird die Route nicht basierend auf einem Timeout entfernt.

-Wert verwendet wird. Jeder andere Wert für dwForwardAge gibt die Anzahl von Sekunden an, bis der TCP/IP-Stapel die Route aus der Netzwerkroutingtabelle entfernt.

Eine von SetIpForwardEntry geänderte Route weist automatisch den Standardwert für dwForwardAge von INFINITE auf.

Eine Reihe von Membern der MIB_IPFORWARDROW Struktur, auf die der Routenparameter verweist, wird derzeit nicht von SetIpForwardEntry verwendet. Zu diesen Membern gehören dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 und dwForwardMetric5.

Verwenden Sie zum Erstellen einer neuen Route in der IP-Routingtabelle die CreateIpForwardEntry-Funktion . Um die IP-Routingtabelle abzurufen, rufen Sie die GetIpForwardTable-Funktion auf.

Unter Windows Vista und höher kann die SetIpForwardEntry-Funktion nur von einem Benutzer aufgerufen werden, der als Mitglied der Gruppe Administratoren angemeldet ist. Wenn SetIpForwardEntry von einem Benutzer aufgerufen wird, der kein Mitglied der Gruppe Administratoren ist, schlägt der Funktionsaufruf fehl, und ERROR_ACCESS_DENIED wird zurückgegeben.

Diese Funktion kann auch aufgrund der Benutzerkontensteuerung (User Account Control, UAC) unter Windows Vista und höher fehlschlagen. Wenn eine Anwendung, die diese Funktion enthält, von einem Benutzer ausgeführt wird, der als Mitglied der Gruppe Administratoren angemeldet ist, die nicht der integrierten Administratorgruppe angehört, schlägt dieser Aufruf fehl, es sei denn, die Anwendung wurde in der Manifestdatei mit einem requestedExecutionLevel gekennzeichnet, der auf requireAdministrator festgelegt ist. Wenn der Anwendung diese Manifestdatei fehlt, muss ein Benutzer, der sich als Mitglied der Gruppe Administratoren angemeldet hat, als der integrierte Administrator, die Anwendung dann in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausführen, damit diese Funktion erfolgreich ist.

Hinweis Unter Windows NT 4.0 und Windows 2000 und höher führt diese Funktion einen privilegierten Vorgang aus. Damit diese Funktion erfolgreich ausgeführt werden kann, muss der Aufrufer als Mitglied der Gruppe Administratoren oder der Gruppe NetworkConfigurationOperators angemeldet sein.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie Sie das Standardgateway in NewGateway ändern. Das einfache Aufrufen von GetIpForwardTable, das Ändern des Gateways und dann das Aufrufen von SetIpForwardEntry ändert nicht die Route, sondern fügt lediglich eine neue Route hinzu. Wenn aus irgendeinem Grund mehrere Standardgateways vorhanden sind, werden diese durch diesen Code gelöscht. Beachten Sie, dass das neue Gateway lebensfähig sein muss. Andernfalls ignoriert TCP/IP die Änderung.

Hinweis Wenn Sie diesen Code ausführen, ändern Sie Ihre IP-Routingtabellen und führen wahrscheinlich dazu, dass die Netzwerkaktivität fehlschlägt.

Windows Vista und höher: Wenn die DeleteIpForwardEntry-Funktion und dann die SetIpForwardEntry-Funktion für denselben Routingtabelleneintrag unter Windows Vista und höher aufgerufen werden, wird ERROR_NOT_FOUND zurückgegeben. Die richtige Möglichkeit zum Replizieren dieses Beispiels unter Windows Vista und höher besteht darin, die CreateIpForwardEntry-Funktion zu verwenden, um den neuen Routingtabelleneintrag zu erstellen und dann den alten Routingtabelleneintrag durch Aufrufen der DeleteIpForwardEntry-Funktion zu löschen.

#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);
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	iphlpapi.h
Bibliothek	Iphlpapi.lib
DLL	Iphlpapi.dll