deleteIpForwardEntry 函数 (iphlpapi.h)

项目
08/24/2023

DeleteIpForwardEntry 函数删除本地计算机的 IPv4 路由表中的现有路由。

语法

IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

parameters

[in] pRoute

指向 MIB_IPFORWARDROW 结构的指针。此结构指定用于标识要删除的路由的信息。调用方必须为结构的 dwForwardIfIndex、 dwForwardDest、 dwForwardMask、 dwForwardNextHop 和 dwForwardProto 成员指定值。

返回值

如果例程成功，函数返回NO_ERROR (零) 。

如果函数失败，则返回值为以下错误代码之一。

错误代码	含义
ERROR_ACCESS_DENIED	拒绝访问。此错误在 Windows Vista 和 Windows Server 2008 上返回，条件如下：用户在本地计算机上缺少所需的管理权限，或者应用程序未在增强的 shell 中运行，因为内置管理员 (运行方式管理员) 。
ERROR_INVALID_PARAMETER	输入参数无效，未执行任何操作。如果 pRoute 参数为 NULL、PMIB_IPFORWARDROW 结构的 dwForwardMask 成员不是有效的 IPv4 子网掩码、dwForwardIfIndex 成员为 NULL，或者 MIB_IPFORWARDROW 结构的其他成员之一无效，则返回此错误。
ERROR_NOT_FOUND	pRoute 参数指向不存在的路由条目。
ERROR_NOT_SUPPORTED	未在本地计算机上配置 IPv4 传输。
(其他)	该函数可能会返回其他错误代码。

如果函数失败，请使用 FormatMessage 获取返回错误的消息字符串。

注解

必须将 route 参数MIB_IPFORWARDROW结构指针的 dwForwardProto 成员设置为 MIB_IPPROTO_NETMGMT否则 DeleteIpForwardEntry 将失败。路由协议标识符用于标识指定路由协议的路由信息。例如， MIB_IPPROTO_NETMGMT 用于通过网络管理（例如动态主机配置协议 (DHCP) 、简单网络管理协议 (SNMP) ）或通过调用 CreateIpForwardEntry、 DeleteIpForwardEntry 或 SetIpForwardEntry 函数来标识 IP 路由设置的路由信息。

在 Windows Vista 和 Windows Server 2008 上， DeleteIpForwardEntry 仅适用于具有单个子接口的接口 (其中接口 LUID 和子接口 LUID 是相同的) 。 MIB_IPFORWARDROW 结构的 dwForwardIfIndex 成员指定接口。

CreateIpForwardEntry 当前不使用路由参数指向的MIB_IPFORWARDROW结构中的许多成员。这些成员包括 dwForwardPolicy、 dwForwardType、 dwForwardAge、 dwForwardNextHopAS、 dwForwardMetric1、 dwForwardMetric2、 dwForwardMetric3、 dwForwardMetric4 和 dwForwardMetric5。

若要修改 IPv4 路由表中的现有路由，请使用 SetIpForwardEntry 函数。若要检索 IPv4 路由表，请调用 GetIpForwardTable 函数。

在 Windows Vista 及更高版本上，只能由以管理员组成员身份登录的用户调用 DeleteIpForwardEntry 函数。如果 DeleteIpForwardEntry 由不是 Administrators 组成员的用户调用，则函数调用将失败并返回 ERROR_ACCESS_DENIED 。

DeleteIpForwardEntry 函数也可能因为 Windows Vista 及更高版本上的用户帐户控制 (UAC) 而失败。如果包含此函数的应用程序由以管理员组成员身份登录（而非内置管理员）的用户执行，则此调用将失败，除非应用程序已在清单文件中标记为 requestedExecutionLevel 设置为 requireAdministrator。如果应用程序缺少此清单文件，则作为管理员组成员（而非内置管理员）登录的用户必须在增强的 shell 中执行应用程序，因为内置管理员 (RunAs 管理员) 才能使此功能成功。

注意在 Windows NT 4.0 和 Windows 2000 及更高版本上，此函数执行特权操作。若要成功执行此函数，调用方必须以管理员组或 NetworkConfigurationOperators 组的成员身份登录。

示例

下面的代码示例演示如何将默认网关更改为 NewGateway。通过调用 GetIpForwardTable，更改网关，然后调用 SetIpForwardEntry 不会更改路由，但会添加新路由。如果存在多个默认网关，此代码将删除它们。请注意，新网关必须可行;否则，TCP/IP 将忽略更改。

注意执行此代码将更改 IP 路由表，并可能导致网络活动失败。

#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);
}

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	iphlpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll