Compartilhar via


Função AddIPAddress (iphlpapi.h)

A função AddIPAddress adiciona o endereço IPv4 especificado ao adaptador especificado.

Sintaxe

IPHLPAPI_DLL_LINKAGE DWORD AddIPAddress(
  [in]  IPAddr Address,
  [in]  IPMask IpMask,
  [in]  DWORD  IfIndex,
  [out] PULONG NTEContext,
  [out] PULONG NTEInstance
);

Parâmetros

[in] Address

O endereço IPv4 a ser adicionado ao adaptador, na forma de uma estrutura IPAddr .

[in] IpMask

A máscara de sub-rede para o endereço IPv4 especificado no parâmetro Address . O parâmetro IPMask usa o mesmo formato que uma estrutura IPAddr .

[in] IfIndex

O índice do adaptador no qual adicionar o endereço IPv4.

[out] NTEContext

Um ponteiro para uma variável ULONG . No retorno bem-sucedido, esse parâmetro aponta para o contexto NTE (Net Table Entry) para o endereço IPv4 que foi adicionado. Posteriormente, o chamador pode usar esse contexto em uma chamada para a função DeleteIPAddress .

[out] NTEInstance

Um ponteiro para uma variável ULONG . No retorno bem-sucedido, esse parâmetro aponta para a instância NTE do endereço IPv4 que foi adicionado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro.

Código de retorno Descrição
ERROR_DEV_NOT_EXIST
O adaptador especificado pelo parâmetro IfIndex não existe.
ERROR_DUP_DOMAINNAME
O endereço IPv4 a ser adicionado especificado no parâmetro Address já existe.
ERROR_GEN_FAILURE
Uma falha geral. Esse erro é retornado para alguns valores especificados no parâmetro Address , como um endereço IPv4 normalmente considerado como endereços de difusão.
ERROR_INVALID_HANDLE
O usuário que tenta fazer a chamada de função não é um administrador.
ERROR_INVALID_PARAMETER
Um ou mais dos parâmetros são inválidos. Esse erro será retornado se os parâmetros NTEContext ou NTEInstance forem NULL. Esse erro também é retornado quando o endereço IP especificado no parâmetro Address é inconsistente com o índice de interface especificado no parâmetro IfIndex (por exemplo, um endereço de loopback em uma interface não loopback).
ERROR_NOT_SUPPORTED
Não há suporte para a chamada de função na versão do Windows na qual ela foi executada.
Outros
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função AddIPAddress é usada para adicionar uma nova entrada de endereço IPv4 em um computador local. O endereço IPv4 adicionado pela função AddIPAddress não é persistente. O endereço IPv4 existe apenas enquanto o objeto do adaptador existir. Reiniciar o computador destrói o endereço IPv4, assim como redefinir manualmente a NIC (cartão de interface de rede). Além disso, determinados eventos PnP podem destruir o endereço.

Para criar um endereço IPv4 que persiste, o método EnableStatic da Classe Win32_NetworkAdapterConfiguration nos controles WMI (Instrumentação de Gerenciamento do Windows) pode ser usado. Os comandos netsh também podem ser usados para criar um endereço IPv4 persistente.

Para obter mais informações, consulte a documentação sobre Netsh.exe na documentação do Windows Sockets.

No Windows Server 2003, Windows XP e Windows 2000, se o endereço IPv4 no parâmetro Address já existir na rede, a função AddIPAddress retornará NO_ERROR e o endereço IPv4 adicionado for 0.0.0.0.

No Windows Vista e posteriores, se o endereço IPv4 passado no parâmetro Address já existir na rede, a função AddIPAddress retornará NO_ERROR e o endereço IPv4 duplicado será adicionado com o membro IP_DAD_STATE na estrutura IP_ADAPTER_UNICAST_ADDRESS definida como IpDadStateDuplicate.

Um endereço IPv4 adicionado usando a função AddIPAddress pode ser posteriormente excluído chamando a função DeleteIPAddress passando o parâmetro NTEContext retornado pela função AddIPAddress .

Para obter informações sobre os tipos de dados IPAddr e IPMask , consulte Tipos de dados do Windows. Para converter um endereço IPv4 entre a notação decimal pontilhada e o formato IPAddr , use as funções inet_addr e inet_ntoa .

No Windows Vista e posteriores, a função CreateUnicastIpAddressEntry pode ser usada para adicionar uma nova entrada de endereço IPv4 ou IPv6 unicast em um computador local.

Exemplos

O exemplo a seguir recupera a tabela de endereços IP para determinar o índice de interface do primeiro adaptador e adiciona o endereço IP especificado na linha de comando ao primeiro adaptador. O endereço IP que foi adicionado é então excluído.

#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);
}

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho iphlpapi.h
Biblioteca Iphlpapi.lib
DLL Iphlpapi.dll

Confira também

CreateUnicastIpAddressEntry

DeleteIPAddress

GetAdapterIndex

GetIpAddrTable

Referência de função auxiliar de IP

Página Inicial do Auxiliar de IP

Ipaddr