CreateIpForwardEntry 関数 (iphlpapi.h)

CreateIpForwardEntry 関数は、ローカル コンピューターの IPv4 ルーティング テーブルにルートを作成します。

構文

IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

パラメーター

[in] pRoute

新しいルートの情報を指定する MIB_IPFORWARDROW 構造体へのポインター。 呼び出し元は、この構造体のすべてのメンバーの値を指定する必要があります。 呼び出し元は 、MIB_IPFORWARDROW の dwForwardProto メンバーの MIB_IPPROTO_NETMGMTを指定する必要があります。

戻り値

関数が成功した場合、関数は NO_ERROR (ゼロ) を返します。

関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。

解説

ルート パラメーターによって指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構造の 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 が同じ) 1 つのサブインターフェイスを持つインターフェイスでのみ機能します。 MIB_IPFORWARDROW構造体の dwForwardIfIndex メンバーは、 インターフェイスを指定します。

ルート パラメーターによって指されるMIB_IPFORWARDROW構造体のメンバーの数は、現在 CreateIpForwardEntry では使用されていません。 これらのメンバーには、 dwForwardPolicy、 dwForwardType、 dwForwardAge、 dwForwardNextHopAS、 dwForwardMetric2、 dwForwardMetric3、 dwForwardMetric4、 dwForwardMetric5 が含まれます。

CreateIpForwardEntry によって作成された新しいルートには、自動的に INFINITE の dwForwardAge の既定値が設定されます。

IPv4 ルーティング テーブル内の既存のルートを変更するには、 SetIpForwardEntry 関数を使用します。 IPv4 ルーティング テーブルを取得するには、 GetIpForwardTable 関数を呼び出します。

Windows Vista 以降では、 CreateIpForwardEntry 関数は、Administrators グループのメンバーとしてログオンしたユーザーのみが呼び出すことができます。 Administrators グループのメンバーではないユーザーが CreateIpForwardEntry を呼び出すと、関数呼び出しは失敗し、 ERROR_ACCESS_DENIED が返されます。

CreateIpForwardEntry 関数は、Windows Vista 以降のユーザー アカウント制御 (UAC) が原因で失敗する可能性もあります。 この関数を含むアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーによって実行された場合、 requestedExecutionLevel が requireAdministrator に設定されたマニフェスト ファイルでアプリケーションがマークされていない限り、この呼び出しは失敗します。 アプリケーションにこのマニフェスト ファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしたユーザーは、この関数を成功させるために、組み込みの Administrator (RunAs 管理者) として拡張シェルでアプリケーションを実行する必要があります。

例

次の例では、既定のゲートウェイを NewGateway に変更する方法を示します。 GetIpForwardTable を呼び出し、ゲートウェイを変更してから SetIpForwardEntry を呼び出すだけで、ルートは変更されず、新しいルートが追加されます。 何らかの理由で複数の既定のゲートウェイが存在する場合、このコードはそれらを削除します。 新しいゲートウェイは実行可能である必要があることに注意してください。それ以外の場合、TCP/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);
}

要件

関連項目

DeleteIpForwardEntry

GetIpForwardTable

GetIpInterfaceEntry

IP ヘルパー関数リファレンス

IP ヘルパーの開始ページ

MIB_IPFORWARDROW

SetIpForwardEntry