CreateIpForwardEntry-Funktion (iphlpapi.h)

Artikel
08/24/2023

Die CreateIpForwardEntry-Funktion erstellt eine Route in der IPv4-Routingtabelle des lokalen Computers.

Syntax

IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Parameter

[in] pRoute

Ein Zeiger auf eine MIB_IPFORWARDROW-Struktur , die die Informationen für die neue Route angibt. Der Aufrufer muss Werte für alle Member dieser Struktur angeben. Der Aufrufer muss MIB_IPPROTO_NETMGMT für das dwForwardProto-Element von MIB_IPFORWARDROW angeben.

Rückgabewert

Die Funktion gibt NO_ERROR (null) zurück, wenn die Funktion erfolgreich ist.

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

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der Zugriff wird verweigert. Dieser Fehler wird unter Windows Vista und Windows Server 2008 unter verschiedenen Bedingungen zurückgegeben, die folgendes umfassen: 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_INVALID_PARAMETER	Ein Eingabeparameter ist ungültig, es wurde keine Aktion ausgeführt. Dieser Fehler wird zurückgegeben, wenn der pRoute-ParameterNULL ist, das dwForwardProto-Element von MIB_IPFORWARDROW nicht auf MIB_IPPROTO_NETMGMT festgelegt wurde, das dwForwardMask-Element der PMIB_IPFORWARDROW-Struktur keine gültige IPv4-Subnetzmaske ist oder eines der anderen Member der MIB_IPFORWARDROW-Struktur ungültig ist.
ERROR_NOT_SUPPORTED	Der IPv4-Transport ist auf dem lokalen Computer nicht konfiguriert.
Andere	Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge 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 CreateIpForwardEntry 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, das über die Netzwerkverwaltung festgelegt ist, 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 aus 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 das Metrikelement der zugeordneten MIB_IPINTERFACE_ROW-Struktur sein. Wenn eine Anwendung die Routenmetrik auf 0 festlegen möchte, sollte das dwForwardMetric1-Element 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 CreateIpForwardEntry nur auf Schnittstellen mit einer einzelnen Unterschnittstelle (wobei die Schnittstellen-LUID und die Unteroberflächen-LUID identisch sind). Das dwForwardIfIndex-Element der MIB_IPFORWARDROW-Struktur gibt die Schnittstelle an.

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

Eine neue Route, die von CreateIpForwardEntry erstellt wurde, weist automatisch den Standardwert für dwForwardAge von INFINITE auf.

Um eine vorhandene Route in der IPv4-Routingtabelle zu ändern, verwenden Sie die SetIpForwardEntry-Funktion . Um die IPv4-Routingtabelle abzurufen, rufen Sie die GetIpForwardTable-Funktion auf.

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

Die CreateIpForwardEntry-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 nicht als mitglied der Gruppe Administratoren als der integrierte Administrator angemeldet ist, schlägt dieser Aufruf fehl, es sei denn, die Anwendung wurde in der Manifestdatei mit einem requestedExecutionLevel-Wert gekennzeichnet, der auf requireAdministrator festgelegt ist. Wenn der Anwendung diese Manifestdatei fehlt, muss ein Benutzer, der sich als anderes Mitglied der Administratorgruppe als der integrierte Administrator angemeldet hat, 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 mit diesem Code gelöscht. Beachten Sie, dass das neue Gateway funktionsfä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 zu einem Fehler bei der Netzwerkaktivität.

#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 = 0xDDCCBBAA;  // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
    
    unsigned int 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
        if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
            printf("Malloc failed. Out of memory.\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 we 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 = 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 resources
    if (pIpForwardTable)
        free(pIpForwardTable);
    if (pRow)
        free(pRow);

    exit(0);
}

Anforderungen


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