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 주소에 대한 NTE(Net Table Entry) 컨텍스트를 가리킵니다. 호출자는 나중에 DeleteIPAddress 함수를 호출할 때 이 컨텍스트를 사용할 수 있습니다.
[out] NTEInstance
ULONG 변수에 대한 포인터입니다. 성공적으로 반환되면 이 매개 변수는 추가된 IPv4 주소에 대한 NTE instance 가리킵니다.
반환 값
함수가 성공하면 반환 값이 NO_ERROR.
함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.
| 반환 코드 | 설명 |
|---|---|
|
IfIndex 매개 변수로 지정된 어댑터가 없습니다. |
|
Address 매개 변수에 지정된 추가할 IPv4 주소가 이미 있습니다. |
|
일반적인 오류입니다. 이 오류는 일반적으로 브로드캐스트 주소로 간주되는 IPv4 주소와 같이 Address 매개 변수에 지정된 일부 값에 대해 반환됩니다. |
|
함수 호출을 시도하는 사용자가 관리자가 아닙니다. |
|
하나 이상의 매개 변수가 잘못되었습니다. NTEContext 또는 NTEInstance 매개 변수가 NULL인 경우 이 오류가 반환됩니다. Address 매개 변수 에 지정된 IP 주소가 IfIndex 매개 변수에 지정된 인터페이스 인덱스와 일치하지 않는 경우에도 이 오류가 반환됩니다(예: 루프백이 아닌 인터페이스의 루프백 주소). |
|
함수 호출은 실행된 Windows 버전에서 지원되지 않습니다. |
|
FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다. |
설명
AddIPAddress 함수는 로컬 컴퓨터에 새 IPv4 주소 항목을 추가하는 데 사용됩니다. AddIPAddress 함수에 의해 추가된 IPv4 주소는 영구적이지 않습니다. IPv4 주소는 어댑터 개체가 있는 경우에만 존재합니다. 컴퓨터를 다시 시작하면 NIC(네트워크 인터페이스 카드)를 수동으로 다시 설정하는 것처럼 IPv4 주소가 삭제됩니다. 또한 특정 PnP 이벤트는 주소를 삭제할 수 있습니다.
유지되는 IPv4 주소를 만들려면 WMI(Windows Management Instrumentation) 컨트롤에서 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 주소는 나중에 AddIPAddress 함수에서 반환된 NTEContext 매개 변수를 전달하는 DeleteIPAddress 함수를 호출하여 삭제할 수 있습니다.
IPAddr 및 IPMask 데이터 형식에 대한 자세한 내용은 Windows 데이터 형식을 참조하세요. 점선 10진수 표기법과 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 |
| 라이브러리 | Iphlpapi.lib |
| DLL | Iphlpapi.dll |