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 (ゼロ) を返します。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| リターン コード | 説明 |
|---|---|
|
アクセスが拒否されました。 このエラーは、Windows Vista および Windows Server 2008 で、次のようないくつかの条件で返されます。ユーザーがローカル コンピューターで必要な管理特権を持っていないか、アプリケーションが組み込みの管理者 (RunAs 管理者) として拡張シェルで実行されていません。 |
|
入力パラメーターが無効です。アクションは実行されませんでした。 このエラーは、pRoute パラメーターが NULL、MIB_IPFORWARDROW の dwForwardProto メンバーがMIB_IPPROTO_NETMGMTに設定されていない、PMIB_IPFORWARDROW構造体の dwForwardMask メンバーが有効な IPv4 サブネット マスクではない、またはMIB_IPFORWARDROW構造体の他のメンバーのいずれかが無効な場合に返されます。 |
|
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構造の 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);
}
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | iphlpapi.h |
| Library | Iphlpapi.lib |
| [DLL] | Iphlpapi.dll |