SetIpForwardEntry 関数 (iphlpapi.h)
SetIpForwardEntry 関数は、ローカル コンピューターの IPv4 ルーティング テーブル内の既存のルートを変更します。
構文
IPHLPAPI_DLL_LINKAGE DWORD SetIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
パラメーター
[in] pRoute
既存のルートの新しい情報を指定する MIB_IPFORWARDROW 構造体へのポインター。 呼び出し元は、この構造体の dwForwardProto メンバーのMIB_IPPROTO_NETMGMTを指定する必要があります。 呼び出し元は、構造体の dwForwardIfIndex、 dwForwardDest、 dwForwardMask、 dwForwardNextHop、 dwForwardPolicy メンバーの値も指定する必要があります。
戻り値
関数が成功した場合、戻り値はNO_ERROR。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| リターン コード | 説明 |
|---|---|
|
アクセスが拒否されました。 このエラーは、Windows Vista および Windows Server 2008 で、次のようないくつかの条件で返されます。ユーザーがローカル コンピューターに必要な管理特権を持っていないか、アプリケーションが組み込みの管理者 (RunAs 管理者) として拡張シェルで実行されていません。 |
|
指定されたファイルが見つかりません。 このエラーは、pRoute パラメーターが指すMIB_IPFORWARDROW構造体の dwForwardIfIndex メンバーによって指定されたネットワーク インターフェイスが見つからなかった場合、Windows Vista 以降で返されます。 |
|
pRoute パラメーターが NULL であるか、SetIpForwardEntry が pRoute が指すメモリから読み取ることができないか、MIB_IPFORWARDROW構造体のメンバーの 1 つが無効です。 |
|
要素が見つかりません。 このエラーは、同じ IPv4 ルート テーブル エントリに対して DeleteIpForwardEntry 関数と SetIpForwardEntry 関数が呼び出されたときに、Windows Vista 以降で返されます。 |
|
要求はサポートされていません。 この値は、IPv4 トランスポートがローカル コンピューターで構成されていない場合に返されます。 このエラーは、ローカル コンピューターで TCP/IP スタックが構成されていない場合、Windows Server 2003 以前でも返されます。 |
|
FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。 |
注釈
ルート パラメーターによって指MIB_IPFORWARDROW構造体の dwForwardProto メンバーを MIB_IPPROTO_NETMGMTに設定する必要があります。それ以外の場合、SetIpForwardEntry は失敗します。 ルーティング プロトコル識別子は、指定されたルーティング プロトコルのルート情報を識別するために使用されます。 たとえば、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 では、 SetIpForwardEntry 関数は、(インターフェイス LUID とサブインターフェイス LUID が同じ) 1 つのサブインターフェイスを持つインターフェイスでのみ機能します。 MIB_IPFORWARDROW構造体の dwForwardIfIndex メンバーは、インターフェイスを指定します。
現在、ルート パラメーターによって指されるMIB_IPFORWARDROW構造体の dwForwardAge メンバーは、SetIpForwardEntry では使用されていません。 dwForwardAge メンバーは、ルーティングとリモート アクセス サービス (RRAS) が実行されている場合にのみ使用され、プロトコル識別子のリファレンス ページで定義されているMIB_IPPROTO_NETMGMT型のルートにのみ使用されます。 dwForwardAge が INFINITE に設定されている場合、タイムアウトに基づいてルートは削除されません
値を表します。 dwForwardAge のその他の値は、TCP/IP スタックがネットワーク ルーティング テーブルからルートを削除するまでの秒数を指定します。
SetIpForwardEntry によって変更されたルートには、自動的に INFINITE の dwForwardAge の既定値が設定されます。
現在、ルート パラメーターによって指されるMIB_IPFORWARDROW構造体のメンバーの数は、SetIpForwardEntry では使用されていません。 これらのメンバーには、 dwForwardPolicy、 dwForwardType、 dwForwardAge、 dwForwardNextHopAS、 dwForwardMetric1、 dwForwardMetric2、 dwForwardMetric3、 dwForwardMetric4、 dwForwardMetric5 が含まれます。
IP ルーティング テーブルに新しいルートを作成するには、 CreateIpForwardEntry 関数を使用します。 IP ルーティング テーブルを取得するには、 GetIpForwardTable 関数を呼び出します。
Windows Vista 以降では、 SetIpForwardEntry 関数は、Administrators グループのメンバーとしてログオンしているユーザーのみが呼び出すことができます。 Administrators グループのメンバーではないユーザーによって SetIpForwardEntry が呼び出された場合、関数呼び出しは失敗し、 ERROR_ACCESS_DENIED が返されます。
この関数は、Windows Vista 以降のユーザー アカウント制御 (UAC) が原因で失敗する場合もあります。 この関数を含むアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーによって実行された場合、 requestedExecutionLevel が requireAdministrator に設定されたマニフェスト ファイルでアプリケーションがマークされていない限り、この呼び出しは失敗します。 アプリケーションにこのマニフェスト ファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーは、この関数を成功させるために、組み込みの Administrator (RunAs 管理者) として拡張シェルでアプリケーションを実行する必要があります。
例
次の例では、既定のゲートウェイを NewGateway に変更する方法を示します。 GetIpForwardTable を呼び出し、ゲートウェイを変更してから SetIpForwardEntry を呼び出すだけで、ルートは変更されず、新しいルートが追加されます。 何らかの理由で複数の既定のゲートウェイが存在する場合、このコードではそれらを削除します。 新しいゲートウェイは実行可能である必要があることに注意してください。それ以外の場合、TCP/IP は変更を無視します。
Windows Vista 以降: DeleteIpForwardEntry 関数と SetIpForwardEntry 関数が Windows Vista 以降の同じルート テーブル エントリに対して呼び出されると、ERROR_NOT_FOUNDが返されます。 この例を Windows Vista 以降でレプリケートする適切な方法は、 CreateIpForwardEntry 関数を使用して新しいルート テーブル エントリを作成し、 DeleteIpForwardEntry 関数を呼び出して古いルート テーブル エントリを削除することです。
#pragma comment(lib, "IPHLPAPI.lib")
// #ifndef WIN32_LEAN_AND_MEAN
// #define WIN32_LEAN_AND_MEAN
// #endif
// #pragma warning(push)
// #pragma warning(disable: 4127)
// #include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>
#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */
int main()
{
// Declare and initialize variables.
/* variables used for SetIfForwardEntry */
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
DWORD 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
pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize);
if (pIpForwardTable == NULL) {
printf("Unable to allocate memory for the IPFORWARDTALE\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 to 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 = SetIpForwardEntry(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);
}
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | iphlpapi.h |
| Library | Iphlpapi.lib |
| [DLL] | Iphlpapi.dll |