SetIpForwardEntry2-Funktion (netioapi.h)

Artikel
02/29/2024

Die SetIpForwardEntry2-Funktion legt die Eigenschaften eines IP-Routeneintrags auf dem lokalen Computer fest.

Syntax

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Route
);

Parameter

[in] Route

Ein Zeiger auf einen MIB_IPFORWARD_ROW2-Struktureintrag für einen IP-Routeneintrag. Das DestinationPrefix-Element des MIB_IPFORWARD_ROW2 muss auf ein gültiges IP-Zielpräfix festgelegt werden, das NextHop-Element des MIB_IPFORWARD_ROW2 muss auf eine gültige IP-Adressfamilie und IP-Adresse festgelegt werden, und das InterfaceLuid - oder InterfaceIndex-Element des MIB_IPFORWARD_ROW2 muss angegeben werden.

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 im Route-Parameter ein NULL-Zeiger übergeben wird, das DestinationPrefix-Element des MIB_IPFORWARD_ROW2, auf das vom Route-Parameter verwiesen wird, nicht angegeben wurde, das NextHop-Element der MIB_IPFORWARD_ROW2, auf die der Route-Parameter verweist, oder die Member InterfaceLuid oder InterfaceIndex der MIB_IPFORWARD_ROW2, auf die vom Route-Parameter verwiesen wird. -Parameter wurden nicht angegeben.
ERROR_NOT_FOUND	Die angegebene Schnittstelle konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn die netzwerkschnittstelle, die vom InterfaceLuid - oder InterfaceIndex-Member der MIB_IPFORWARD_ROW2 angegeben wurde, auf die der Route-Parameter verweist, nicht gefunden werden konnte.
Andere	Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

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

Die SetIpForwardEntry2-Funktion wird verwendet, um die Eigenschaften für einen vorhandenen IP-Routeneintrag auf einem lokalen Computer festzulegen.

Das DestinationPrefix-Element in der MIB_IPFORWARD_ROW2 Struktur, auf die der Parameter Route verweist, muss mit einem gültigen IP-Adresspräfix und einer gültigen Familie initialisiert werden. Das NextHop-Element in der MIB_IPFORWARD_ROW2 Struktur, auf die der Parameter Route verweist, muss mit einer gültigen IP-Adresse und Familie initialisiert werden. Darüber hinaus muss mindestens einer der folgenden Member in der MIB_IPFORWARD_ROW2 Struktur, die auf den Parameter Route 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 dieser Member verwendet, um die Schnittstelle zu bestimmen, auf der die Unicast-IP-Adresse hinzugefügt werden soll. Wenn kein Wert für das InterfaceLuid-Element festgelegt wurde (die Werte dieses Members wurden auf 0 festgelegt), wird als Nächstes das InterfaceIndex-Element verwendet, um die Schnittstelle zu bestimmen.

Der Routenmetrikoffset , der im Metrikelement der MIB_IPFORWARD_ROW2-Struktur angegeben ist, auf die der Route-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 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 SetIpForwardEntry2-Funktion aufgerufen wird. Diese Member werden vom Netzwerkstapel festgelegt und können nicht mithilfe der SetIpForwardEntry2-Funktion geändert werden.

Die SetIpForwardEntry2-Funktion schlägt fehl, wenn die Member DestinationPrefix und NextHop der MIB_IPFORWARD_ROW2 , auf die der Parameter Route verweist, nicht mit einem IP-Routeneintrag auf der angegebenen Schnittstelle übereinstimmen.

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

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