CreateIpForwardEntry 函式 (iphlpapi.h)

發行項
08/24/2023

CreateIpForwardEntry函式會在本機電腦的 IPv4 路由表中建立路由。

語法

IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

參數

[in] pRoute

指定新路由資訊的 MIB_IPFORWARDROW 結構的指標。呼叫端必須為此結構的所有成員指定值。呼叫端必須為 MIB_IPFORWARDROW 的 dwForwardProto 成員指定 MIB_IPPROTO_NETMGMT。

傳回值

如果函式成功，函式會 傳回NO_ERROR (零) 。

如果函式失敗，傳回值就是下列其中一個錯誤碼。

傳回碼	描述
ERROR_ACCESS_DENIED	存取遭到拒絕。 Windows Vista 和 Windows Server 2008 上傳回此錯誤的情況包括下列各項：使用者缺少本機電腦的必要系統管理許可權，或應用程式未在增強殼層中執行，因為 RunAs 系統管理員 (RunAs 系統管理員) 。
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可用來識別透過網路管理所設定 IP 路由的路由資訊，例如動態主機設定通訊協定 (DHCP) 、簡單網路管理通訊協定 (SNMP) ，或呼叫CreateIpForwardEntry、DeleteIpForwardEntry或SetIpForwardEntry函式。

在 Windows Vista 和 Windows Server 2008 上，pRoute參數所指向之 MIB_IPFORWARDROW結構的dwForwardMetric1成員中指定的路由計量，代表新增至相關聯介面之MIB_IPINTERFACE_ROW結構之Metric成員中所指定之介面計量的組合。因此，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所建立的新路由會自動有 INFINITE的 dwForwardAge預設值。

若要修改 IPv4 路由表中的現有路由，請使用 SetIpForwardEntry 函式。若要擷取 IPv4 路由表，請呼叫 GetIpForwardTable 函式。

在 Windows Vista 和更新版本上， CreateIpForwardEntry 函式只能由以 Administrators 群組成員身分登入的使用者呼叫。如果 CreateIpForwardEntry 是由不是 Administrators 群組成員的使用者呼叫，則函式呼叫將會失敗，並 傳回ERROR_ACCESS_DENIED 。

CreateIpForwardEntry函式也可能因為 Windows Vista 和更新版本的使用者帳戶控制 (UAC) 而失敗。如果包含此函式的應用程式是由以內建系統管理員以外的 Administrators 群組成員身分登入的使用者所執行，除非應用程式已在資訊清單檔案中標示 為 requestedExecutionLevel 設定為 requireAdministrator，否則此呼叫將會失敗。如果應用程式缺少此資訊清單檔，則以系統管理員以外的 Administrators 群組成員身分登入的使用者，必須在增強的殼層中執行應用程式，因為內建的 Administrator (RunAs 系統管理員) ，此函式才能成功。

注意在 Windows NT 4.0 和 Windows 2000 和更新版本上，此函式會執行特殊許可權作業。若要讓此函式順利執行，呼叫端必須以 Administrators 群組或 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
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll