Freigeben über


SetIpInterfaceEntry-Funktion (netioapi.h)

Die SetIpInterfaceEntry-Funktion legt die Eigenschaften einer IP-Schnittstelle auf dem lokalen Computer fest.

Syntax

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpInterfaceEntry(
  [in, out] PMIB_IPINTERFACE_ROW Row
);

Parameter

[in, out] Row

Ein Zeiger auf einen MIB_IPINTERFACE_ROW Struktureintrag für eine Schnittstelle. Bei der Eingabe muss das Familienmitglied des MIB_IPINTERFACE_ROW auf AF_INET6 oder AF_INET festgelegt werden, und das InterfaceLuid - oder InterfaceIndex-Element des MIB_IPINTERFACE_ROW muss angegeben werden. Bei erfolgreicher Rückgabe wird das InterfaceLuid-Element der MIB_IPINTERFACE_ROW ausgefüllt, wenn das InterfaceIndex-Element des MIB_IPINTERFACE_ROW-Eintrags angegeben wurde.

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_FILE_NOT_FOUND
Die angegebene Datei wurde nicht gefunden. Dieser Fehler wird zurückgegeben, wenn die NETZWERKschnittstellen-LUID oder der Schnittstellenindex, der vom InterfaceLuid- oder InterfaceIndex-Member des MIB_IPINTERFACE_ROW angegeben wurde, auf den der Row-Parameter verweist, kein Wert auf dem lokalen Computer war.
ERROR_INVALID_PARAMETER
Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn im Row-Parameter ein NULL-Zeiger übergeben wird, das Family-Element des MIB_IPINTERFACE_ROW, auf das vom Row-Parameter verwiesen wird, nicht als AF_INET oder AF_INET6 angegeben wurde, oder wenn die InterfaceLuid- oder InterfaceIndex-Member des MIB_IPINTERFACE_ROW, auf das vom Row-Parameter verwiesen wird, nicht angegeben wurden.
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_IPINTERFACE_ROW angegeben wird, auf das vom Row-Parameter verwiesen wird, nicht mit der IP-Adressfamilie übereinstimmt, die im Familienmitglied in der MIB_IPINTERFACE_ROW-Struktur angegeben ist.
Andere
Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

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

Die SetIpInterfaceEntry-Funktion kann verwendet werden, um einen vorhandenen IP-Schnittstelleneintrag zu ändern.

Bei der Eingabe muss das Familienmitglied in der MIB_IPINTERFACE_ROW Struktur, auf die vom Parameter Row verwiesen wird, entweder AF_INET oder AF_INET6 initialisiert werden. Darüber hinaus muss bei der Eingabe mindestens eines der folgenden Member in der MIB_IPINTERFACE_ROW-Struktur initialisiert werden, die auf den Row-Parameter verweist: 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. 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.

Bei der Ausgabe wird das InterfaceLuid-Element der MIB_IPINTERFACE_ROW Struktur ausgefüllt, auf die der Row-Parameter verweist, wenn der InterfaceIndex angegeben wurde.

Die Elemente MaxReassemblySize, MinRouterAdvertisementInterval, MaxRouterAdvertisementInterval , Connected, SupportsWakeUpPatterns, SupportsNeighborDiscovery, SupportsRouterDiscovery, ReachableTime, TransmitOffload und ReceiveOffload der MIB_IPINTERFACE_ROW Struktur, auf die von der Zeile verwiesen wird, werden ignoriert, wenn die SetIpInterfaceEntry-Funktion aufgerufen wird. Diese Elemente werden vom Netzwerkstapel festgelegt und können nicht mit der SetIpInterfaceEntry-Funktion geändert werden.

Eine Anwendung ruft in der Regel die GetIpInterfaceTable-Funktion auf, um die IP-Schnittstelleneinträge auf dem lokalen Computer abzurufen, oder die GetIpInterfaceEntry-Funktion aufrufen, um nur den IP-Schnittstelleneintrag abzurufen, der geändert werden soll. Die MIB_IPINTERFACE_ROW-Struktur für den spezifischen IP-Schnittstelleneintrag kann dann geändert werden, und ein Zeiger auf diese Struktur wird an die SetIpInterfaceEntry-Funktion im Row-Parameter übergeben. Für IPv4 darf eine Anwendung jedoch nicht versuchen, das SitePrefixLength-Element der MIB_IPINTERFACE_ROW-Struktur zu ändern. Für IPv4 muss das SitePrefixLength-Element auf 0 festgelegt werden.

Eine weitere mögliche Methode zum Ändern eines vorhandenen IP-Schnittstelleneintrags ist die InitializeIpInterfaceEntry-Funktion , um die Felder eines MIB_IPINTERFACE_ROW Struktureintrags mit Standardwerten zu initialisieren. Legen Sie dann das Family-Element und entweder die Member InterfaceIndex oder InterfaceLuid in der MIB_IPINTERFACE_ROW Struktur fest, auf die vom Row-Parameter verwiesen wird, um mit der zu ändernden IP-Schnittstelle übereinzupassen. Eine Anwendung kann dann die Felder im MIB_IPINTERFACE_ROW Eintrag ändern, den sie ändern möchte, und dann die SetIpInterfaceEntry-Funktion aufrufen. Für IPv4 darf eine Anwendung jedoch nicht versuchen, das SitePrefixLength-Element der MIB_IPINTERFACE_ROW-Struktur zu ändern. Für IPv4 muss das SitePrefixLength-Element auf 0 festgelegt werden. Bei diesem Ansatz ist Vorsicht geboten, da die einzige Möglichkeit, alle geänderten Felder zu ermitteln, darin besteht, die Felder im MIB_IPINTERFACE_ROW des jeweiligen IP-Schnittstelleneintrags mit Feldern zu vergleichen, die von der InitializeIpInterfaceEntry-Funktion festgelegt werden, wenn ein MIB_IPINTERFACE_ROW mit Standardwerten initialisiert wird.

Ein nicht privilegierter gleichzeitiger Zugriff auf mehrere Netzwerke mit unterschiedlichen Sicherheitsanforderungen schafft eine Sicherheitslücke und ermöglicht es einer nicht privilegierten Anwendung, Daten versehentlich zwischen den beiden Netzwerken weiterzuspeichern. Ein typisches Beispiel ist der gleichzeitige Zugriff auf ein virtuelles privates Netzwerk (VPN) und das Internet. Windows Server 2003 und Windows XP verwenden ein schwaches Hostmodell, bei dem RAS einen solchen gleichzeitigen Zugriff verhindert, indem die Routenmetrik aller Standardrouten über andere Schnittstellen erhöht wird. Daher wird der gesamte Datenverkehr über die VPN-Schnittstelle weitergeleitet, was die andere Netzwerkkonnektivität beeinträchtigt.

Unter Windows Vista und höher wird standardmäßig ein starkes Hostmodell verwendet. Wenn eine Quell-IP-Adresse in der Routensuche mithilfe von GetBestRoute2 oder GetBestRoute angegeben wird, ist die Routensuche auf die Schnittstelle der Quell-IP-Adresse beschränkt. Die Änderung der Routenmetrik durch RAS hat keine Auswirkungen, da die Liste der potenziellen Routen nicht einmal die Route für die VPN-Schnittstelle enthält, wodurch Datenverkehr ins Internet zugelassen wird. Das DisableDefaultRoutes-Element des MIB_IPINTERFACE_ROW kann verwendet werden, um die Standardroute für eine Schnittstelle zu deaktivieren. Dieser Member kann als Sicherheitsmaßnahme von VPN-Clients verwendet werden, um das Split Tunneling einzuschränken, wenn das Split Tunneling vom VPN-Client nicht erforderlich ist. Ein VPN-Client kann die SetIpInterfaceEntry-Funktion aufrufen, um den DisableDefaultRoutes-Member bei Bedarf auf TRUE festzulegen. Ein VPN-Client kann den aktuellen Zustand des DisableDefaultRoutes-Members abfragen, indem er die GetIpInterfaceEntry-Funktion aufruft .

The

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

GetBestRoute

GetBestRoute2

GetIfEntry2

GetIfTable2

GetIfTable2Ex

GetIpInterfaceEntry

GetIpInterfaceTable

IP-Hilfsfunktionsreferenz

InitializeIpInterfaceEntry

MIB_IF_ROW2

MIB_IF_TABLE2

MIB_IPINTERFACE_ROW

MIB_IPINTERFACE_TABLE

NotifyIpInterfaceChange