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
);
parameters
[in] Address
要添加到适配器的 IPv4 地址，采用 IPAddr 结构的形式。
[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 地址已存在。 |
|
常规故障。 对于 Address 参数中指定的某些值（例如通常被视为广播地址的 IPv4 地址），将返回此错误。 |
|
尝试进行函数调用的用户不是管理员。 |
|
一个或多个参数无效。 如果 NTEContext 或 NTEInstance 参数为 NULL，则返回此错误。 当 Address 参数中指定的 IP 地址与 IfIndex 参数中指定的接口索引不一致时，也会返回此错误 (例如，非环回接口上的环回地址) 。 |
|
运行函数的 Windows 版本不支持函数调用。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
AddIPAddress 函数用于在本地计算机上添加新的 IPv4 地址条目。 AddIPAddress 函数添加的 IPv4 地址不是永久性的。 只要适配器对象存在，IPv4 地址就存在。 重新启动计算机会销毁 IPv4 地址，手动重置网络接口卡 (NIC) 。 此外，某些 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 地址时，IP_ADAPTER_UNICAST_ADDRESS 结构中的 IP_DAD_STATE 成员设置为 IpDadStateDuplicate。
以后可以通过调用 DeleteIPAddress 函数来传递 AddIPAddress 函数返回的 NTEContext 参数，删除使用 AddIPAddress 函数添加的 IPv4 地址。
有关 IPAddr 和 IPMask 数据类型的信息，请参阅 Windows 数据类型。 若要在点点十进制表示法和 IPAddr 格式之间转换 IPv4 地址，请使用 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 |