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
要新增至介面卡的 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 Sockets 檔中 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成員新增。
稍後可以藉由呼叫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 專業版 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | iphlpapi.h |
| 程式庫 | Iphlpapi.lib |
| Dll | Iphlpapi.dll |