deleteIpForwardEntry 函式 (iphlpapi.h)

發行項
08/24/2023

DeleteIpForwardEntry函式會刪除本機電腦的 IPv4 路由表中現有的路由。

語法

IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

參數

[in] pRoute

MIB_IPFORWARDROW結構的指標。此結構會指定要識別要刪除之路由的資訊。呼叫端必須指定結構的 dwForwardIfIndex、 dwForwardDest、 dwForwardMask、 dwForwardNextHop和 dwForwardProto 成員的值。

傳回值

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

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

錯誤碼	意義
ERROR_ACCESS_DENIED	存取遭到拒絕。 Windows Vista 和 Windows Server 2008 上傳回此錯誤的情況包括下列各項：使用者缺少本機電腦的必要系統管理許可權，或應用程式未在增強殼層中執行，因為 RunAs 系統管理員 (RunAs 系統管理員) 。
ERROR_INVALID_PARAMETER	輸入參數無效，未採取任何動作。如果pRoute參數為Null、PMIB_IPFORWARDROW結構的dwForwardMask成員不是有效的 IPv4 子網路遮罩、dwForwardIfIndex成員為Null，或MIB_IPFORWARDROW結構的其中一個其他成員無效，就會傳回此錯誤。
ERROR_NOT_FOUND	pRoute參數會指向不存在的路由專案。
ERROR_NOT_SUPPORTED	本機電腦上未設定 IPv4 傳輸。
(其他)	函式可能會傳回其他錯誤碼。

如果函式失敗，請使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

路由參數MIB_IPFORWARDROW結構指標的dwForwardProto成員必須設定為MIB_IPPROTO_NETMGMT否則DeleteIpForwardEntry將會失敗。路由通訊協定識別碼可用來識別指定之路由通訊協定的路由資訊。例如，MIB_IPPROTO_NETMGMT可用來識別透過網路管理所設定 IP 路由的路由資訊，例如動態主機設定通訊協定 (DHCP) 、簡單網路管理通訊協定 (SNMP) ，或呼叫CreateIpForwardEntry、DeleteIpForwardEntry或SetIpForwardEntry函式。

在 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 函式只能由以 Administrators 群組成員身分登入的使用者呼叫。如果 DeleteIpForwardEntry 是由不是 Administrators 群組成員的使用者呼叫，則函式呼叫將會失敗，並 傳回ERROR_ACCESS_DENIED 。

DeleteIpForwardEntry函式也可能因為使用者帳戶控制 (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 = 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
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll