Функция 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
Маска подсети для IPv4-адреса, указанного в параметре Address . Параметр IPMask использует тот же формат, что и структура IPAddr .
[in] IfIndex
Индекс адаптера, к которому добавляется IPv4-адрес.
[out] NTEContext
Указатель на переменную ULONG . При успешном возвращении этот параметр указывает на контекст NTE для добавленного IPv4-адреса. Позднее вызывающий объект может использовать этот контекст в вызове функции DeleteIPAddress .
[out] NTEInstance
Указатель на переменную ULONG . При успешном возвращении этот параметр указывает на экземпляр NTE для добавленного IPv4-адреса.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращается один из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
Адаптер, указанный параметром IfIndex , не существует. |
|
Добавляемый IPv4-адрес, указанный в параметре Address , уже существует. |
|
Общий сбой. Эта ошибка возвращается для некоторых значений, указанных в параметре Address , например IPv4-адрес, который обычно считается широковещательным адресом. |
|
Пользователь, пытающийся выполнить вызов функции, не является администратором. |
|
Один или несколько параметров недопустимы. Эта ошибка возвращается, если параметры NTEContext или NTEInstance имеют значение NULL. Эта ошибка также возвращается, если IP-адрес, указанный в параметре Address , не соответствует индексу интерфейса, указанному в параметре IfIndex (например, адрес замыкания на себя в интерфейсе без замыкания на себя). |
|
Вызов функции не поддерживается в той версии Windows, в которой она была запущена. |
|
Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки. |
Комментарии
Функция AddIPAddress используется для добавления новой записи IPv4-адреса на локальном компьютере. IPv4-адрес, добавленный функцией AddIPAddress , не является постоянным. IPv4-адрес существует только при условии, что существует объект адаптера. Перезагрузка компьютера удаляет IPv4-адрес, как и сброс сетевого интерфейса вручную карта (NIC). Кроме того, некоторые события PnP могут уничтожить адрес.
Чтобы создать сохраняемый IPv4-адрес, можно использовать метод EnableStatic класса Win32_NetworkAdapterConfiguration в элементах управления инструментария управления Windows (WMI). Команды netsh также можно использовать для создания постоянного IPv4-адреса.
Дополнительные сведения см. в документации по Netsh.exe документации по сокетам Windows.
В Windows Server 2003, Windows XP и Windows 2000, если IPv4-адрес в параметре Address уже существует в сети, функция AddIPAddress возвращает NO_ERROR , а добавленный IPv4-адрес — 0.0.0.0.
В Windows Vista и более поздних версиях, если IPv4-адрес, переданный в параметр Address , уже существует в сети, функция AddIPAddress возвращает NO_ERROR , а повторяющийся IPv4-адрес добавляется с элементом IP_DAD_STATE в структуре IP_ADAPTER_UNICAST_ADDRESS , для параметра IpDadStateDuplicate.
IPv4-адрес, добавленный с помощью функции AddIPAddress , можно позже удалить, вызвав функцию DeleteIPAddress , передав параметр NTEContext , возвращаемый функцией AddIPAddress .
Сведения о типах данных IPAddr и IPMask см. в разделе Типы данных Windows. Чтобы преобразовать IPv4-адрес между пунктирной десятичной нотацией и форматом 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 |
| Header | iphlpapi.h |
| Библиотека | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
См. также раздел
Справочник по вспомогательной функции IP