DeleteIpForwardEntry-Funktion (iphlpapi.h)
Die DeleteIpForwardEntry-Funktion löscht eine vorhandene Route in der IPv4-Routingtabelle des lokalen Computers.
Syntax
IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parameter
[in] pRoute
Ein Zeiger auf eine MIB_IPFORWARDROW-Struktur . Diese Struktur gibt Informationen an, die die zu löschende Route identifizieren. Der Aufrufer muss Werte für die Elemente dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop und dwForwardProto der Struktur angeben.
Rückgabewert
Die Funktion gibt NO_ERROR (null) zurück, wenn die Routine erfolgreich ist.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.
| Fehlercode | Bedeutung |
|---|---|
|
Der Zugriff wird verweigert. Dieser Fehler wird unter Windows Vista und Windows Server 2008 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. |
|
Ein Eingabeparameter ist ungültig, es wurde keine Aktion ausgeführt. Dieser Fehler wird zurückgegeben, wenn der pRoute-ParameterNULL ist, das dwForwardMask-Element der PMIB_IPFORWARDROW-Struktur keine gültige IPv4-Subnetzmaske ist, das dwForwardIfIndex-ElementNULL ist oder eines der anderen Member der MIB_IPFORWARDROW-Struktur ungültig ist. |
|
Der pRoute-Parameter verweist auf einen Routeneintrag, der nicht vorhanden ist. |
|
Der IPv4-Transport ist auf dem lokalen Computer nicht konfiguriert. |
|
Die Funktion gibt möglicherweise andere Fehlercodes zurück. |
Wenn die Funktion fehlschlägt, verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.
Hinweise
Der dwForwardProto-MemberMIB_IPFORWARDROW Strukturzeigers durch den routenparameter muss auf MIB_IPPROTO_NETMGMT festgelegt werden, andernfalls schlägt DeleteIpForwardEntry 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, die über die Netzwerkverwaltung festgelegt werden, 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 funktioniert DeleteIpForwardEntry nur auf Schnittstellen mit einer einzelnen Unterschnittstelle (wobei die Schnittstellen-LUID und die Unteroberfläche LUID identisch sind). Der dwForwardIfIndex-Member 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, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 und dwForwardMetric5.
Verwenden Sie die SetIpForwardEntry-Funktion , um eine vorhandene Route in der IPv4-Routingtabelle zu ändern. Rufen Sie die GetIpForwardTable-Funktion auf, um die IPv4-Routingtabelle abzurufen.
Unter Windows Vista und höher kann die DeleteIpForwardEntry-Funktion nur von einem Benutzer aufgerufen werden, der als Mitglied der Gruppe Administratoren angemeldet ist. Wenn DeleteIpForwardEntry 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 DeleteIpForwardEntry-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 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.
Beispiele
Das folgende Codebeispiel zeigt, wie Sie das Standardgateway in NewGateway ändern. Wenn Sie GetIpForwardTable aufrufen, das Gateway ändern und dann SetIpForwardEntry aufrufen, wird die Route nicht geändert, sondern eine neue hinzugefügt. Wenn mehrere Standardgateways vorhanden sind, werden diese von diesem Code gelöscht. Beachten Sie, dass das neue Gateway praktikabel sein muss; Andernfalls ignoriert TCP/IP die Änderung.
#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 = 0xDDBBCCAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int i;
// Identify the required size of the buffer.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
// Allocate memory for the table.
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Retrieve the table.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
}
if (dwStatus != ERROR_SUCCESS) {
printf("getIpForwardTable failed.\n");
if (pIpForwardTable)
free(pIpForwardTable);
exit(1);
}
// Search for the required row in the table. The default gateway has a destination
// of 0.0.0.0. Be aware the table continues to be searched, but only
// one row is copied. This is to ensure that, if multiple gateways exist, all of them are deleted.
//
for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
if (pIpForwardTable->table[i].dwForwardDest == 0) {
// The default gateway was found.
if (!pRow) {
// Allocate memory to store the row. This is easier than manually filling
// the row structure; only the gateway address is changed.
//
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 other properties of the route will
// remain the same.
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 the memory.
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 |