CreateIpForwardEntry 函数 (iphlpapi.h)

项目
08/24/2023

CreateIpForwardEntry 函数在本地计算机的 IPv4 路由表中创建路由。

语法

IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

parameters

[in] pRoute

指向 MIB_IPFORWARDROW 结构的指针，该结构指定新路由的信息。调用方必须为此结构的所有成员指定值。调用方必须为 MIB_IPFORWARDROW 的 dwForwardProto 成员指定 MIB_IPPROTO_NETMGMT。

返回值

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

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

返回代码	说明
ERROR_ACCESS_DENIED	拒绝访问。此错误在 Windows Vista 和 Windows Server 2008 上返回，条件如下：用户在本地计算机上缺少所需的管理权限，或者应用程序未在增强的 shell 中运行，因为内置管理员 (运行方式管理员) 。
ERROR_INVALID_PARAMETER	输入参数无效，未执行任何操作。如果 pRoute 参数为 NULL、MIB_IPFORWARDROW 的 dwForwardProto 成员未设置为 MIB_IPPROTO_NETMGMT、PMIB_IPFORWARDROW 结构的 dwForwardMask 成员不是有效的 IPv4 子网掩码，或者 MIB_IPFORWARDROW 结构的某个其他成员无效，则返回此错误。
ERROR_NOT_SUPPORTED	未在本地计算机上配置 IPv4 传输。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

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

在 Windows Vista 和 Windows Server 2008 上，pRoute 参数指向的MIB_IPFORWARDROW结构的 dwForwardMetric1 成员中指定的路由指标表示添加到关联接口的 MIB_IPINTERFACE_ROW 结构的指标成员中指定的路由指标的组合。因此，MIB_IPFORWARDROW 结构的 dwForwardMetric1 成员应等于或大于关联MIB_IPINTERFACE_ROW结构的 Metric 成员。如果应用程序想要将路由指标设置为 0，则应将MIB_IPFORWARDROW结构的 dwForwardMetric1 成员设置为等于关联MIB_IPINTERFACE_ROW结构的 Metric 成员中指定的接口指标的值。应用程序可以通过调用 GetIpInterfaceEntry 函数来检索接口指标。

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

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

CreateIpForwardEntry 创建的新路由将自动具有 DWForwardAge 的默认值 INFINITE。

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

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

CreateIpForwardEntry 函数也可能因为用户帐户控制 (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 = 0xDDCCBBAA;  // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
    
    unsigned int i;

// Find out how big our buffer needs to be.
    dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
        // Allocate the memory for the table
        if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
            printf("Malloc failed. Out of memory.\n");
            exit(1);
        }
        // Now get the table.
        dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    }

    if (dwStatus != ERROR_SUCCESS) {
        printf("getIpForwardTable failed.\n");
        if (pIpForwardTable)
            free(pIpForwardTable);
        exit(1);
    }
    // Search for the row in the table we want. The default gateway has a destination
    // of 0.0.0.0. Notice that we continue looking through the table, but copy only 
    // one row. This is so that if there happen to be multiple default gateways, we can
    // be sure to delete them all.
    for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
        if (pIpForwardTable->table[i].dwForwardDest == 0) {
            // We have found the default gateway.
            if (!pRow) {
                // Allocate some memory to store the row in; this is easier than filling
                // in the row structure ourselves, and we can be sure we change only the
                // gateway address.
                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 the other properties of the route will
    // be the same as they were previously.
    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 resources
    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