Функция 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.

Если функция завершается сбоем, возвращается один из следующих кодов ошибок.

Код возврата	Описание
ERROR_DEV_NOT_EXIST	Адаптер, указанный параметром IfIndex , не существует.
ERROR_DUP_DOMAINNAME	Добавляемый IPv4-адрес, указанный в параметре Address , уже существует.
ERROR_GEN_FAILURE	Общий сбой. Эта ошибка возвращается для некоторых значений, указанных в параметре Address , например IPv4-адрес, который обычно считается широковещательным адресом.
ERROR_INVALID_HANDLE	Пользователь, пытающийся выполнить вызов функции, не является администратором.
ERROR_INVALID_PARAMETER	Один или несколько параметров недопустимы. Эта ошибка возвращается, если параметры NTEContext или NTEInstance имеют значение NULL. Эта ошибка также возвращается, если IP-адрес, указанный в параметре Address , не соответствует индексу интерфейса, указанному в параметре IfIndex (например, адрес замыкания на себя в интерфейсе без замыкания на себя).
ERROR_NOT_SUPPORTED	Вызов функции не поддерживается в той версии 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

См. также раздел

CreateUnicastIpAddressEntry

DeleteIPAddress

GetAdapterIndex

GetIpAddrTable

Справочник по вспомогательной функции IP

Начальная страница вспомогательного ip-адреса

IPAddr

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2023-08-24