Freigeben über


CreateIpForwardEntry2-Funktion (netioapi.h)

Die CreateIpForwardEntry2-Funktion erstellt einen neuen IP-Routeneintrag auf dem lokalen Computer.

Syntax

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API CreateIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Row
);

Parameter

[in] Row

Ein Zeiger auf einen MIB_IPFORWARD_ROW2 Struktureintrag für einen IP-Routeneintrag.

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 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_INVALID_PARAMETER
Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein NULL-Zeiger im Row-Parameter übergeben wird, das DestinationPrefix-Element des MIB_IPFORWARD_ROW2 , auf das der Row-Parameter verweist, nicht angegeben wurde, das NextHop-Element des MIB_IPFORWARD_ROW2 , auf das der Row-Parameter verweist, oder die Member InterfaceLuid oder InterfaceIndex des MIB_IPFORWARD_ROW2 , auf das vom Row-Parameter verwiesen wird. Parameter wurden nicht angegeben. Dieser Fehler wird auch zurückgegeben, wenn das im MIB_IPFORWARD_ROW2 angegebene PreferredLifetime-Member größer als das ValidLifetime-Element ist oder wenn die SitePrefixLength im MIB_IPFORWARD_ROW2 größer als die präfixlänge ist, die im DestinationPrefix angegeben ist.
ERROR_NOT_FOUND
Die angegebene Schnittstelle konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn die Netzwerkschnittstelle, die vom InterfaceLuid - oder InterfaceIndex-Member des MIB_IPNET_ROW2 durch den Row-Parameter angegeben wurde, nicht gefunden werden konnte.
ERROR_NOT_SUPPORTED
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn die angegebene Schnittstelle keine Routen unterstützt. Dieser Fehler wird auch zurückgegeben, wenn sich kein IPv4-Stapel auf dem lokalen Computer befindet und AF_INET in der Adressfamilie im DestinationPrefix-Member des MIB_IPFORWARD_ROW2 angegeben wurde, auf den der Row-Parameter verweist. Dieser Fehler wird auch zurückgegeben, wenn sich kein IPv6-Stapel auf dem lokalen Computer befindet und AF_INET6 für die Adressfamilie im DestinationPrefix-Element angegeben wurde.
ERROR_OBJECT_ALREADY_EXISTS
Das Objekt ist bereits vorhanden. Dieser Fehler wird zurückgegeben, wenn das DestinationPrefix-Element des MIB_IPFORWARD_ROW2, auf das vom Row-Parameter verwiesen wird, ein Duplikat eines vorhandenen IP-Routeneintrags auf der Schnittstelle ist, die vom InterfaceLuid- oder InterfaceIndex-Member des MIB_IPFORWARD_ROW2 angegeben wird.
Andere
Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die CreateIpForwardEntry2-Funktion ist unter Windows Vista und höher definiert.

Die CreateIpForwardEntry2-Funktion wird verwendet, um einen neuen Eintrag für benachbarte IP-Adressen auf einem lokalen Computer hinzuzufügen. Die InitializeIpForwardEntry-Funktion sollte verwendet werden, um die Member eines MIB_IPFORWARD_ROW2 Struktureintrags mit Standardwerten zu initialisieren. Eine Anwendung kann dann die Member im MIB_IPFORWARD_ROW2 Eintrag ändern, den sie ändern möchte, und dann die Funktion CreateIpForwardEntry2 aufrufen.

Das DestinationPrefix-Element in der MIB_IPFORWARD_ROW2 Struktur, auf die der Row-Parameter verweist, muss mit einem gültigen IPv4- oder IPv6-Adresspräfix initialisiert werden. Das NextHop-Element in der MIB_IPFORWARD_ROW2-Struktur , auf die der Row-Parameter verweist, muss für eine gültige IPv4- oder IPv6-Adresse und -Familie initialisiert werden. Darüber hinaus muss mindestens eines der folgenden Member in der MIB_IPFORWARD_ROW2-Struktur , die auf den Row-Parameter verweist, für die Schnittstelle initialisiert werden: InterfaceLuid oder InterfaceIndex.

Die Felder werden in der oben aufgeführten Reihenfolge verwendet. Wenn also InterfaceLuid angegeben wird, wird dieses Element verwendet, um die Schnittstelle zu bestimmen, für die der IP-Routeneintrag hinzugefügt werden soll. Wenn kein Wert für das InterfaceLuid-Element festgelegt wurde (die Werte dieses Members wurden auf Null festgelegt), wird das InterfaceIndex-Element als nächstes verwendet, um die Schnittstelle zu bestimmen.

Der im Metrikelement derMIB_IPFORWARD_ROW2 Struktur angegebene Routenmetrik, auf die vom Row-Parameter verwiesen wird, stellt nur einen Teil der vollständigen Routenmetrik dar. Die vollständige Metrik ist eine Kombination aus diesem Routenmetrikoffset, der der Schnittstellenmetrik hinzugefügt wird, die im Metrikelement der MIB_IPINTERFACE_ROW Struktur der zugeordneten Schnittstelle angegeben ist. Eine Anwendung kann die Schnittstellenmetrik abrufen, indem sie die GetIpInterfaceEntry-Funktion aufruft .

Die Elemente Age und Origin der MIB_IPFORWARD_ROW2 Struktur, auf die die Zeile verweist, werden ignoriert, wenn die CreateIpForwardEntry2-Funktion aufgerufen wird. Diese Elemente werden vom Netzwerkstapel festgelegt und können nicht mit der CreateIpForwardEntry2-Funktion festgelegt werden.

Die CreateIpForwardEntry2-Funktion schlägt fehl, wenn die Member DestinationPrefix und NextHop des MIB_IPFORWARD_ROW2, auf die vom Row-Parameter verwiesen wird, ein Duplikat eines vorhandenen IP-Routeneintrags auf der Schnittstelle sind, die im InterfaceLuid- oder InterfaceIndex-Member angegeben ist.

Die CreateIpForwardEntry2-Funktion kann nur von einem Benutzer aufgerufen werden, der als Mitglied der Gruppe Administratoren angemeldet ist. Wenn CreateIpForwardEntry2 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 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.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile netioapi.h (include Iphlpapi.h)
Bibliothek Iphlpapi.lib
DLL Iphlpapi.dll

Weitere Informationen

DeleteIpForwardEntry2

GetBestRoute2

GetIpForwardEntry2

GetIpForwardTable2

GetIpInterfaceEntry

InitializeIpForwardEntry

MIB_IPFORWARD_ROW2

MIB_IPFORWARD_TABLE2

MIB_IPINTERFACE_ROW

NotifyRouteChange2

SetIpForwardEntry2