DeleteIpForwardEntry 関数 (iphlpapi.h)
DeleteIpForwardEntry 関数は、ローカル コンピューターの IPv4 ルーティング テーブル内の既存のルートを削除します。
構文
IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
パラメーター
[in] pRoute
MIB_IPFORWARDROW構造体へのポインター。 この構造体は、削除するルートを識別する情報を指定します。 呼び出し元は、構造体の dwForwardIfIndex、 dwForwardDest、 dwForwardMask、 dwForwardNextHop、 および dwForwardProto メンバーの値を指定する必要があります。
戻り値
ルーチンが成功した場合、関数は NO_ERROR (ゼロ) を返します。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| エラー コード | 意味 |
|---|---|
|
アクセスが拒否されました。 このエラーは、Windows Vista および Windows Server 2008 で、次のようないくつかの条件で返されます。ユーザーがローカル コンピューターに必要な管理特権を持っていないか、アプリケーションが組み込みの管理者 (RunAs 管理者) として拡張シェルで実行されていません。 |
|
入力パラメーターが無効です。アクションは実行されませんでした。 このエラーは、pRoute パラメーターが NULL、PMIB_IPFORWARDROW構造体の dwForwardMask メンバーが有効な IPv4 サブネット マスクではない、dwForwardIfIndex メンバーが NULL、またはMIB_IPFORWARDROW構造体の他のメンバーのいずれかが無効な場合に返されます。 |
|
pRoute パラメーターは、存在しないルート エントリを指します。 |
|
IPv4 トランスポートがローカル コンピューターで構成されていません。 |
|
関数は他のエラー コードを返す場合があります。 |
関数が失敗した場合は、 FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。
解説
ルート パラメーターによって への構造体ポインター MIB_IPFORWARDROWdwForwardProto メンバーを MIB_IPPROTO_NETMGMT に設定する必要があります。それ以外の場合、DeleteIpForwardEntry は失敗します。 ルーティング プロトコル識別子は、指定されたルーティング プロトコルのルート情報を識別するために使用されます。 たとえば、MIB_IPPROTO_NETMGMTは、動的ホスト構成プロトコル (DHCP)、簡易ネットワーク管理プロトコル (SNMP)、CreateIpForwardEntry、DeleteIpForwardEntry、または SetIpForwardEntry 関数の呼び出しによって、 ネットワーク管理によって設定された IP ルーティングのルート情報を識別するために使用されます。
Windows Vista および Windows Server 2008 では、 DeleteIpForwardEntry は 1 つのサブインターフェイス (インターフェイス LUID とサブインターフェイス LUID が同じ) を持つインターフェイスでのみ機能します。 MIB_IPFORWARDROW構造体の dwForwardIfIndex メンバーは、インターフェイスを指定します。
ルート パラメーターによって指されるMIB_IPFORWARDROW構造体のメンバーの数は、現在 CreateIpForwardEntry では使用されていません。 これらのメンバーには、 dwForwardPolicy、 dwForwardType、 dwForwardAge、 dwForwardNextHopAS、 dwForwardMetric1、 dwForwardMetric2、 dwForwardMetric3、 dwForwardMetric4、 dwForwardMetric5 が含まれます。
IPv4 ルーティング テーブル内の既存のルートを変更するには、 SetIpForwardEntry 関数を使用します。 IPv4 ルーティング テーブルを取得するには、 GetIpForwardTable 関数を呼び出します。
Windows Vista 以降では、 DeleteIpForwardEntry 関数は、Administrators グループのメンバーとしてログオンしているユーザーのみが呼び出すことができます。 Administrators グループのメンバーではないユーザーが DeleteIpForwardEntry を呼び出すと、関数呼び出しは失敗し、 ERROR_ACCESS_DENIED が返されます。
DeleteIpForwardEntry 関数は、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 = 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 |
| Library | Iphlpapi.lib |
| [DLL] | Iphlpapi.dll |