AddIPAddress 関数 (iphlpapi.h)
AddIPAddress 関数は、指定した IPv4 アドレスを指定したアダプターに追加します。
構文
IPHLPAPI_DLL_LINKAGE DWORD AddIPAddress(
[in] IPAddr Address,
[in] IPMask IpMask,
[in] DWORD IfIndex,
[out] PULONG NTEContext,
[out] PULONG NTEInstance
);
パラメーター
[in] Address
IPAddr 構造体の形式でアダプターに追加する IPv4 アドレス。
[in] IpMask
Address パラメーターで指定された IPv4 アドレスのサブネット マスク。 IPMask パラメーターは、IPAddr 構造体と同じ形式を使用します。
[in] IfIndex
IPv4 アドレスを追加するアダプターのインデックス。
[out] NTEContext
ULONG 変数へのポインター。 正常に戻った場合、このパラメーターは、追加された IPv4 アドレスの Net Table Entry (NTE) コンテキストを指します。 呼び出し元は、後で DeleteIPAddress 関数の呼び出しでこのコンテキストを使用できます。
[out] NTEInstance
ULONG 変数へのポインター。 正常に戻った場合、このパラメーターは、追加された IPv4 アドレスの NTE インスタンスを指します。
戻り値
関数が成功した場合、戻り値はNO_ERROR。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
リターン コード | 説明 |
---|---|
|
IfIndex パラメーターで指定されたアダプターが存在しません。 |
|
Address パラメーターで指定されている追加する IPv4 アドレスは既に存在します。 |
|
一般的なエラー。 このエラーは、通常はブロードキャスト アドレスと見なされる IPv4 アドレスなど、 Address パラメーターで指定された一部の値に対して返されます。 |
|
関数呼び出しを行おうとしているユーザーは管理者ではありません。 |
|
1 つ以上のパラメーターが無効です。 このエラーは、 NTEContext パラメーターまたは NTEInstance パラメーターが NULL の場合に返されます。 このエラーは、 Address パラメーターで指定された IP アドレスが IfIndex パラメーターで指定されたインターフェイス インデックス (非ループバック インターフェイスのループバック アドレスなど) と矛盾している場合にも返されます。 |
|
関数呼び出しは、実行された Windows のバージョンではサポートされていません。 |
|
FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。 |
解説
AddIPAddress 関数は、ローカル コンピューターに新しい IPv4 アドレス エントリを追加するために使用されます。 AddIPAddress 関数によって追加された IPv4 アドレスは永続的ではありません。 IPv4 アドレスは、アダプター オブジェクトが存在する限り存在します。 ネットワーク インターフェイス カード (NIC) を手動でリセットする場合と同様に、コンピューターを再起動すると IPv4 アドレスが破棄されます。 また、特定の PnP イベントによってアドレスが破棄される場合があります。
永続化する IPv4 アドレスを作成するには、Windows Management Instrumentation (WMI) コントロール の Win32_NetworkAdapterConfiguration クラスの EnableStatic メソッド を使用できます。 netsh コマンドを使用して、永続的な IPv4 アドレスを作成することもできます。
詳細については、Windows ソケットのドキュメントの Netsh.exe に関するドキュメントを参照してください。
Windows Server 2003、Windows XP、および Windows 2000 では、 Address パラメーターの IPv4 アドレスがネットワーク上に既に存在する場合、 AddIPAddress 関数は NO_ERROR を返し、追加される IPv4 アドレスは 0.0.0.0 です。
Windows Vista 以降では、Address パラメーターで渡された IPv4 アドレスが既にネットワーク上に存在する場合、AddIPAddress 関数はNO_ERRORを返し、重複する IPv4 アドレスは、ipDadStateDuplicate に設定されたIP_ADAPTER_UNICAST_ADDRESS構造体のIP_DAD_STATE メンバーと共に追加されます。
AddIPAddress 関数を使用して追加された IPv4 アドレスは、後で DeleteIPAddress 関数を呼び出して、AddIPAddress 関数によって返される NTEContext パラメーターを渡すことで削除できます。
IPAddr データ型と IPMask データ型の詳細については、「Windows データ型」を参照してください。 IPv4 アドレスをドット 10 進表記と IPAddr 形式の間で変換するには、 inet_addr 関数と inet_ntoa 関数を使用します。
Windows Vista 以降では、 CreateUnicastIpAddressEntry 関数を使用して、ローカル コンピューターに新しいユニキャスト IPv4 または IPv6 アドレス エントリを追加できます。
例
次の例では、最初のアダプターのインターフェイス インデックスを決定するために IP アドレス テーブルを取得し、コマンド ラインで指定された IP アドレスを最初のアダプターに追加します。 追加された IP アドレスが削除されます。
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
#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 __cdecl main(int argc, char **argv)
{
/* Variables used by GetIpAddrTable */
PMIB_IPADDRTABLE pIPAddrTable;
DWORD dwSize = 0;
DWORD dwRetVal = 0;
IN_ADDR IPAddr;
DWORD ifIndex;
/* IPv4 address and subnet mask we will be adding */
UINT iaIPAddress;
UINT iaIPMask;
/* Variables where handles to the added IP are returned */
ULONG NTEContext = 0;
ULONG NTEInstance = 0;
/* Variables used to return error message */
LPVOID lpMsgBuf;
// Validate the parameters
if (argc != 3) {
printf("usage: %s IPAddress SubnetMask\n", argv[0]);
exit(1);
}
iaIPAddress = inet_addr(argv[1]);
if (iaIPAddress == INADDR_NONE) {
printf("usage: %s IPAddress SubnetMask\n", argv[0]);
exit(1);
}
iaIPMask = inet_addr(argv[2]);
if (iaIPMask == INADDR_NONE) {
printf("usage: %s IPAddress SubnetMask\n", argv[0]);
exit(1);
}
// Before calling AddIPAddress we use GetIpAddrTable to get
// an adapter to which we can add the IP.
pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(sizeof (MIB_IPADDRTABLE));
if (pIPAddrTable == NULL) {
printf("Error allocating memory needed to call GetIpAddrTable\n");
exit (1);
}
else {
dwSize = 0;
// Make an initial call to GetIpAddrTable to get the
// necessary size into the dwSize variable
if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
ERROR_INSUFFICIENT_BUFFER) {
FREE(pIPAddrTable);
pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);
}
if (pIPAddrTable == NULL) {
printf("Memory allocation failed for GetIpAddrTable\n");
exit(1);
}
}
// Make a second call to GetIpAddrTable to get the
// actual data we want
if ((dwRetVal = GetIpAddrTable(pIPAddrTable, &dwSize, 0)) == NO_ERROR) {
// Save the interface index to use for adding an IP address
ifIndex = pIPAddrTable->table[0].dwIndex;
printf("\n\tInterface Index:\t%ld\n", ifIndex);
IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwAddr;
printf("\tIP Address: \t%s (%lu%)\n", inet_ntoa(IPAddr),
pIPAddrTable->table[0].dwAddr);
IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwMask;
printf("\tSubnet Mask: \t%s (%lu%)\n", inet_ntoa(IPAddr),
pIPAddrTable->table[0].dwMask);
IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwBCastAddr;
printf("\tBroadCast Address:\t%s (%lu%)\n", inet_ntoa(IPAddr),
pIPAddrTable->table[0].dwBCastAddr);
printf("\tReassembly size: \t%lu\n\n",
pIPAddrTable->table[0].dwReasmSize);
} else {
printf("Call to GetIpAddrTable failed with error %d.\n", dwRetVal);
if (pIPAddrTable)
FREE(pIPAddrTable);
exit(1);
}
if (pIPAddrTable) {
FREE(pIPAddrTable);
pIPAddrTable = NULL;
}
if ((dwRetVal = AddIPAddress(iaIPAddress,
iaIPMask,
ifIndex,
&NTEContext, &NTEInstance)) == NO_ERROR) {
printf("\tIPv4 address %s was successfully added.\n", argv[1]);
} else {
printf("AddIPAddress failed with error: %d\n", dwRetVal);
if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, dwRetVal, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language
(LPTSTR) & lpMsgBuf, 0, NULL)) {
printf("\tError: %s", lpMsgBuf);
LocalFree(lpMsgBuf);
exit(1);
}
}
// Delete the IP we just added using the NTEContext
// variable where the handle was returned
if ((dwRetVal = DeleteIPAddress(NTEContext)) == NO_ERROR) {
printf("\tIPv4 address %s was successfully deleted.\n", argv[1]);
} else {
printf("\tDeleteIPAddress failed with error: %d\n", dwRetVal);
exit(1);
}
exit(0);
}
要件
サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
対象プラットフォーム | Windows |
ヘッダー | iphlpapi.h |
Library | Iphlpapi.lib |
[DLL] | Iphlpapi.dll |