CreateIpForwardEntry2-Funktion

Artikel
06/15/2023

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

Syntax

NETIOAPI_API CreateIpForwardEntry2(
  _In_ const MIB_IPFORWARD_ROW2 *Row
);

Parameter

Zeile [in]
Ein Zeiger auf einen MIB_IPFORWARD_ROW2 Struktureintrag für einen IP-Routeneintrag.

Rückgabewert

CreateIpForwardEntry2 gibt STATUS_SUCCESS zurück, wenn die Funktion erfolgreich ist.

Wenn die Funktion fehlschlägt, gibt CreateIpForwardEntry2 einen der folgenden Fehlercodes zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn eine der folgenden Situationen auftritt: Im Row-Parameter wird ein NULL-Zeiger übergeben. Das DestinationPrefix-Element der MIB_IPFORWARD_ROW2 Struktur, auf die der Row-Parameter verweist, wurde nicht angegeben. Das NextHop-Element der MIB_IPFORWARD_ROW2-Struktur wurde nicht angegeben. Sowohl InterfaceLuid - als auch InterfaceIndex-Member der MIB_IPFORWARD_ROW2-Struktur wurden nicht angegeben. Das PreferredLifetime-Element der MIB_IPFORWARD_ROW2-Struktur ist größer als das ValidLifetime-Element . Das SitePrefixLength-Element der MIB_IPFORWARD_ROW2-Struktur ist größer als die Präfixlänge, die vom DestinationPrefix-Member angegeben wird. Dieser Fehler wird zurückgegeben, wenn ein NULL-Zeiger im Row-Parameter übergeben wird, das DestinationPrefix-Element der MIB_IPFORWARD_ROW2-Struktur , auf das vom Row-Parameter verwiesen wird, nicht angegeben wurde, das NextHop-Element der MIB_IPFORWARD_ROW2-Struktur nicht angegeben wurde oder die Elemente InterfaceLuid und InterfaceIndex der MIB_IPFORWARD_ROW2-Struktur nicht angegeben wurden. Dieser Fehler wird auch zurückgegeben, wenn der In der MIB_IPFORWARD_ROW2-Struktur angegebene PreferredLifetime-Member größer als der ValidLifetime-Member ist oder wenn die SitePrefixLength in der MIB_IPFORWARD_ROW2-Struktur größer als die Präfixlänge ist, die im DestinationPrefix-Member angegeben ist.
STATUS_NOT_FOUND	Die angegebene Schnittstelle konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn die Funktion die Netzwerkschnittstelle nicht finden kann, die vom InterfaceLuid- oder InterfaceIndex-Member der MIB_IPNET_ROW2 Struktur angegeben wird, auf die der Row-Parameter verweist.
STATUS_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn die angegebene Schnittstelle keine Routen unterstützt. Dieser Fehler wird zurückgegeben, wenn sich kein IPv4-Stapel auf dem lokalen Computer befindet und AF_INET in der Adressfamilie im DestinationPrefix-Element der MIB_IPFORWARD_ROW2-Struktur angegeben wurde, auf die der Row-Parameter verweist, oder 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 der MIB_IPFORWARD_ROW2-Struktur, auf die der Row-Parameter verweist, ein Duplikat eines vorhandenen IP-Routeneintrags auf der Schnittstelle ist, der vom InterfaceLuid- oder InterfaceIndex-Member der MIB_IPFORWARD_ROW2-Struktur angegeben wird.
Andere	Verwenden Sie die FormatMessage-Funktion , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Bemerkungen

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

Ihr Treiber muss die folgenden Member der MIB_IPFORWARD_ROW2 Struktur initialisieren, auf die der Row-Parameter verweist:

Legen Sie DestinationPrefix auf ein gültiges IPv4- oder IPv6-Adresspräfix fest.
Legen Sie NextHop auf eine gültige IPv4- oder IPv6-Adresse und -Familie fest.
Legen Sie InterfaceLuid oder InterfaceIndex auf den LUID- oder Indexwert der Schnittstelle fest.

Die Member InterfaceLuid und InterfaceIndex werden in der zuvor 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 (der Wert dieses Members wurde auf Null festgelegt), wird das InterfaceIndex-Element als nächstes verwendet, um die Schnittstelle zu bestimmen.

Der Routenmetrikoff, der im Metrikelement der MIB_IPFORWARD_ROW2-Struktur angegeben ist, auf die der Row-Parameter verweist, 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 wird. Ein Treiber kann die Schnittstellenmetrik abrufen, indem er die GetIpInterfaceEntry-Funktion aufruft .

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

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

Anforderungen

Zielplattform	Universell
Version	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Header	Netioapi.h (einschließlich Netioapi.h)
Bibliothek	Netio.lib
IRQL	< DISPATCH_LEVEL