Compartilhar via


Função GetAdaptersAddresses (iphlpapi.h)

A função GetAdaptersAddresses recupera os endereços associados aos adaptadores no computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE ULONG GetAdaptersAddresses(
  [in]      ULONG                 Family,
  [in]      ULONG                 Flags,
  [in]      PVOID                 Reserved,
  [in, out] PIP_ADAPTER_ADDRESSES AdapterAddresses,
  [in, out] PULONG                SizePointer
);

Parâmetros

[in] Family

A família de endereços dos endereços a serem recuperados. Esse parâmetro deve usar um dos valores a seguir.

Valor Significado
AF_UNSPEC
0
Retornar endereços IPv4 e IPv6 associados a adaptadores com IPv4 ou IPv6 habilitados.
AF_INET
2
Retornar somente endereços IPv4 associados a adaptadores com IPv4 habilitado.
AF_INET6
23
Retornar somente endereços IPv6 associados a adaptadores com IPv6 habilitado.

[in] Flags

O tipo de endereços a serem recuperados. Os valores possíveis são definidos no arquivo de cabeçalho Iptypes.h . Observe que o arquivo de cabeçalho Iptypes.h é incluído automaticamente em Iphlpapi.h e nunca deve ser usado diretamente.

Esse parâmetro é uma combinação dos valores a seguir. Se esse parâmetro for zero, os endereços IP unicast, anycast e multicast serão retornados.

Valor Significado
GAA_FLAG_SKIP_UNICAST
0x0001
Não retorne endereços unicast.
GAA_FLAG_SKIP_ANYCAST
0x0002
Não retorne endereços anycast IPv6.
GAA_FLAG_SKIP_MULTICAST
0x0004
Não retorne endereços multicast.
GAA_FLAG_SKIP_DNS_SERVER
0x0008
Não retorne endereços de servidores DNS.
GAA_FLAG_INCLUDE_PREFIX
0x0010
Retornar uma lista de prefixos de endereço IP neste adaptador. Quando esse sinalizador é definido, os prefixos de endereço IP são retornados para endereços IPv6 e IPv4.

Esse sinalizador tem suporte no Windows XP com SP1 e posterior.

GAA_FLAG_SKIP_FRIENDLY_NAME
0x0020
Não retorne o nome amigável do adaptador.
GAA_FLAG_INCLUDE_WINS_INFO
0x0040
Retornar endereços de servidores WINS (Serviço de Nome da Internet) do Windows.

Esse sinalizador tem suporte no Windows Vista e posterior.

GAA_FLAG_INCLUDE_GATEWAYS
0x0080
Retornar os endereços dos gateways padrão.

Esse sinalizador tem suporte no Windows Vista e posterior.

GAA_FLAG_INCLUDE_ALL_INTERFACES
0x0100
Retornar endereços para todas as interfaces NDIS.

Esse sinalizador tem suporte no Windows Vista e posterior.

GAA_FLAG_INCLUDE_ALL_COMPARTMENTS
0x0200
Retornar endereços em todos os compartimentos de roteamento.

No momento, esse sinalizador não tem suporte e é reservado para uso futuro.

GAA_FLAG_INCLUDE_TUNNEL_BINDINGORDER
0x0400
Retornar os endereços do adaptador classificados na ordem de associação de túnel. Esse sinalizador tem suporte no Windows Vista e posterior.

[in] Reserved

Esse parâmetro não é usado no momento, mas é reservado para uso futuro do sistema. O aplicativo de chamada deve passar NULL para esse parâmetro.

[in, out] AdapterAddresses

Um ponteiro para um buffer que contém uma lista vinculada de estruturas de IP_ADAPTER_ADDRESSES no retorno bem-sucedido.

[in, out] SizePointer

Um ponteiro para uma variável que especifica o tamanho do buffer apontado por AdapterAddresses.

Valor retornado

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS (definido com o mesmo valor que 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_ADDRESS_NOT_ASSOCIATED
Um endereço ainda não foi associado ao ponto de extremidade de rede. As informações de concessão do DHCP estavam disponíveis.
ERROR_BUFFER_OVERFLOW
O tamanho do buffer indicado pelo parâmetro SizePointer é muito pequeno para manter as informações do adaptador ou o parâmetro AdapterAddresses é NULL. O parâmetro SizePointer retornou pontos para o tamanho necessário do buffer para manter as informações do adaptador.
ERROR_INVALID_PARAMETER
Um dos parâmetros é inválido. Esse erro é retornado para qualquer uma das seguintes condições: o parâmetro SizePointer é NULL, o parâmetro Address não é AF_INET, AF_INET6 ou AF_UNSPEC ou as informações de endereço para os parâmetros solicitados são maiores que ULONG_MAX.
ERROR_NOT_ENOUGH_MEMORY
Recursos de memória insuficientes estão disponíveis para concluir a operação.
ERROR_NO_DATA
Nenhum endereço foi encontrado para os parâmetros solicitados.
Outros
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

O
A função GetAdaptersAddresses pode recuperar informações para endereços IPv4 e IPv6.

Os endereços são retornados como uma lista vinculada de estruturas de IP_ADAPTER_ADDRESSES no buffer apontado pelo parâmetro AdapterAddresses . O aplicativo que chama a função GetAdaptersAddresses deve alocar a quantidade de memória necessária para retornar as estruturas de IP_ADAPTER_ADDRESSES apontadas pelo parâmetro AdapterAddresses . Quando essas estruturas retornadas não são mais necessárias, o aplicativo deve liberar a memória alocada. Isso pode ser feito chamando a função HeapAlloc para alocar memória e, posteriormente, chamando a função HeapFree para liberar a memória alocada, conforme mostrado no código de exemplo. Outras funções livres e alocação de memória podem ser usadas desde que a mesma família de funções seja usada para a alocação e a função gratuita.

GetAdaptersAddresses é implementado apenas como uma chamada de função síncrona. A função GetAdaptersAddresses requer uma quantidade significativa de recursos de rede e tempo para ser concluída, pois todas as tabelas de interface de rede de baixo nível devem ser percorridas.

Um método que pode ser usado para determinar a memória necessária para retornar as estruturas IP_ADAPTER_ADDRESSESapontadas pelo parâmetro AdapterAddresses é passar um tamanho de buffer muito pequeno, conforme indicado no parâmetro SizePointer na primeira chamada para a função GetAdaptersAddresses , de modo que a função falhará com ERROR_BUFFER_OVERFLOW. Quando o valor retornado é ERROR_BUFFER_OVERFLOW, o parâmetro SizePointer retorna pontos para o tamanho necessário do buffer para manter as informações do adaptador. Observe que é possível que o tamanho do buffer necessário para as estruturas de IP_ADAPTER_ADDRESSESapontadas pelo parâmetro AdapterAddresses altere entre chamadas subsequentes para a função GetAdaptersAddresses se um endereço do adaptador for adicionado ou removido. No entanto, esse método de usar a função GetAdaptersAddresses é altamente desencorajado. Esse método requer chamar a função GetAdaptersAddresses várias vezes.

O método recomendado para chamar a função GetAdaptersAddresses é pré-alocar um buffer de trabalho de 15 KB apontado pelo parâmetro AdapterAddresses . Em computadores típicos, isso reduz drasticamente as chances de que a função GetAdaptersAddresses retorne ERROR_BUFFER_OVERFLOW, o que exigiria chamar a função GetAdaptersAddresses várias vezes. O código de exemplo ilustra esse método de uso.

Em versões anteriores ao Windows 10, a ordem na qual os adaptadores aparecem na lista retornada por essa função pode ser controlada na pasta Conexões de Rede: selecione o item de menu Configurações Avançadas no menu Avançado. A partir do Windows 10, a ordem na qual os adaptadores aparecem na lista é determinada pela métrica de rota IPv4 ou IPv6.

Se o GAA_FLAG_INCLUDE_ALL_INTERFACES estiver definido, todos os adaptadores NDIS serão recuperados mesmo os endereços associados aos adaptadores não associados a uma família de endereços especificada no parâmetro Family . Quando esse sinalizador não estiver definido, somente os endereços associados a um adaptador habilitado para a família de endereços especificada no parâmetro Family serão retornados.

O tamanho da estrutura de IP_ADAPTER_ADDRESSES foi alterado no Windows XP com Service Pack 1 (SP1) e posterior. Vários membros adicionais foram adicionados a essa estrutura. O tamanho da estrutura de IP_ADAPTER_ADDRESSES também foi alterado no Windows Vista e posterior. Vários membros adicionais foram adicionados a essa estrutura. O tamanho da estrutura de IP_ADAPTER_ADDRESSES também foi alterado no Windows Vista com Service Pack 1 (SP1) e posterior e noWindows Server 2008 e posterior. Um membro adicional foi adicionado a essa estrutura. O membro Length da estrutura IP_ADAPTER_ADDRESSES retornado na lista vinculada de estruturas no buffer apontado pelo parâmetro AdapterAddresses deve ser usado para determinar qual versão da estrutura IP_ADAPTER_ADDRESSES está sendo usada.

A função GetIpAddrTable recupera a tabela de mapeamento de endereços IPv4 da interface em um computador local e retorna essas informações em uma estrutura MIB_IPADDRTABLE .

No SDK (Platform Software Development Kit) lançado para o Windows Server 2003 e versões anteriores, o valor retornado para a função GetAdaptersAddresses foi definido como um DWORD, em vez de um ULONG.

A estrutura SOCKET_ADDRESS é usada na estrutura IP_ADAPTER_ADDRESSES apontada pelo parâmetro AdapterAddresses . No SDK (Software Development Kit) do Microsoft Windows lançado para Windows Vista e posterior, a organização dos arquivos de cabeçalho foi alterada e a estrutura de SOCKET_ADDRESS é definida no arquivo de cabeçalho Ws2def.h , que é incluído automaticamente pelo arquivo de cabeçalho Winsock2.h . No SDK da Plataforma lançado para Windows Server 2003 e Windows XP, a estrutura SOCKET_ADDRESS é declarada no arquivo de cabeçalho Winsock2.h . Para usar a estrutura IP_ADAPTER_ADDRESSES , o arquivo de cabeçalho Winsock2.h deve ser incluído antes do arquivo de cabeçalho Iphlpapi.h .

Exemplos

Este exemplo recupera a estrutura IP_ADAPTER_ADDRESSES para os adaptadores associados ao sistema e imprime alguns membros para cada interface do adaptador.

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

// Link with Iphlpapi.lib
#pragma comment(lib, "IPHLPAPI.lib")

#define WORKING_BUFFER_SIZE 15000
#define MAX_TRIES 3

#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)
{

    /* Declare and initialize variables */

    DWORD dwRetVal = 0;

    unsigned int i = 0;

    // Set the flags to pass to GetAdaptersAddresses
    ULONG flags = GAA_FLAG_INCLUDE_PREFIX;

    // default to unspecified address family (both)
    ULONG family = AF_UNSPEC;

    LPVOID lpMsgBuf = NULL;

    PIP_ADAPTER_ADDRESSES pAddresses = NULL;
    ULONG outBufLen = 0;
    ULONG Iterations = 0;

    PIP_ADAPTER_ADDRESSES pCurrAddresses = NULL;
    PIP_ADAPTER_UNICAST_ADDRESS pUnicast = NULL;
    PIP_ADAPTER_ANYCAST_ADDRESS pAnycast = NULL;
    PIP_ADAPTER_MULTICAST_ADDRESS pMulticast = NULL;
    IP_ADAPTER_DNS_SERVER_ADDRESS *pDnServer = NULL;
    IP_ADAPTER_PREFIX *pPrefix = NULL;

    if (argc != 2) {
        printf(" Usage: getadapteraddresses family\n");
        printf("        getadapteraddresses 4 (for IPv4)\n");
        printf("        getadapteraddresses 6 (for IPv6)\n");
        printf("        getadapteraddresses A (for both IPv4 and IPv6)\n");
        exit(1);
    }

    if (atoi(argv[1]) == 4)
        family = AF_INET;
    else if (atoi(argv[1]) == 6)
        family = AF_INET6;

    printf("Calling GetAdaptersAddresses function with family = ");
    if (family == AF_INET)
        printf("AF_INET\n");
    if (family == AF_INET6)
        printf("AF_INET6\n");
    if (family == AF_UNSPEC)
        printf("AF_UNSPEC\n\n");

    // Allocate a 15 KB buffer to start with.
    outBufLen = WORKING_BUFFER_SIZE;

    do {

        pAddresses = (IP_ADAPTER_ADDRESSES *) MALLOC(outBufLen);
        if (pAddresses == NULL) {
            printf
                ("Memory allocation failed for IP_ADAPTER_ADDRESSES struct\n");
            exit(1);
        }

        dwRetVal =
            GetAdaptersAddresses(family, flags, NULL, pAddresses, &outBufLen);

        if (dwRetVal == ERROR_BUFFER_OVERFLOW) {
            FREE(pAddresses);
            pAddresses = NULL;
        } else {
            break;
        }

        Iterations++;

    } while ((dwRetVal == ERROR_BUFFER_OVERFLOW) && (Iterations < MAX_TRIES));

    if (dwRetVal == NO_ERROR) {
        // If successful, output some information from the data we received
        pCurrAddresses = pAddresses;
        while (pCurrAddresses) {
            printf("\tLength of the IP_ADAPTER_ADDRESS struct: %ld\n",
                   pCurrAddresses->Length);
            printf("\tIfIndex (IPv4 interface): %u\n", pCurrAddresses->IfIndex);
            printf("\tAdapter name: %s\n", pCurrAddresses->AdapterName);

            pUnicast = pCurrAddresses->FirstUnicastAddress;
            if (pUnicast != NULL) {
                for (i = 0; pUnicast != NULL; i++)
                    pUnicast = pUnicast->Next;
                printf("\tNumber of Unicast Addresses: %d\n", i);
            } else
                printf("\tNo Unicast Addresses\n");

            pAnycast = pCurrAddresses->FirstAnycastAddress;
            if (pAnycast) {
                for (i = 0; pAnycast != NULL; i++)
                    pAnycast = pAnycast->Next;
                printf("\tNumber of Anycast Addresses: %d\n", i);
            } else
                printf("\tNo Anycast Addresses\n");

            pMulticast = pCurrAddresses->FirstMulticastAddress;
            if (pMulticast) {
                for (i = 0; pMulticast != NULL; i++)
                    pMulticast = pMulticast->Next;
                printf("\tNumber of Multicast Addresses: %d\n", i);
            } else
                printf("\tNo Multicast Addresses\n");

            pDnServer = pCurrAddresses->FirstDnsServerAddress;
            if (pDnServer) {
                for (i = 0; pDnServer != NULL; i++)
                    pDnServer = pDnServer->Next;
                printf("\tNumber of DNS Server Addresses: %d\n", i);
            } else
                printf("\tNo DNS Server Addresses\n");

            printf("\tDNS Suffix: %wS\n", pCurrAddresses->DnsSuffix);
            printf("\tDescription: %wS\n", pCurrAddresses->Description);
            printf("\tFriendly name: %wS\n", pCurrAddresses->FriendlyName);

            if (pCurrAddresses->PhysicalAddressLength != 0) {
                printf("\tPhysical address: ");
                for (i = 0; i < (int) pCurrAddresses->PhysicalAddressLength;
                     i++) {
                    if (i == (pCurrAddresses->PhysicalAddressLength - 1))
                        printf("%.2X\n",
                               (int) pCurrAddresses->PhysicalAddress[i]);
                    else
                        printf("%.2X-",
                               (int) pCurrAddresses->PhysicalAddress[i]);
                }
            }
            printf("\tFlags: %ld\n", pCurrAddresses->Flags);
            printf("\tMtu: %lu\n", pCurrAddresses->Mtu);
            printf("\tIfType: %ld\n", pCurrAddresses->IfType);
            printf("\tOperStatus: %ld\n", pCurrAddresses->OperStatus);
            printf("\tIpv6IfIndex (IPv6 interface): %u\n",
                   pCurrAddresses->Ipv6IfIndex);
            printf("\tZoneIndices (hex): ");
            for (i = 0; i < 16; i++)
                printf("%lx ", pCurrAddresses->ZoneIndices[i]);
            printf("\n");

            printf("\tTransmit link speed: %I64u\n", pCurrAddresses->TransmitLinkSpeed);
            printf("\tReceive link speed: %I64u\n", pCurrAddresses->ReceiveLinkSpeed);

            pPrefix = pCurrAddresses->FirstPrefix;
            if (pPrefix) {
                for (i = 0; pPrefix != NULL; i++)
                    pPrefix = pPrefix->Next;
                printf("\tNumber of IP Adapter Prefix entries: %d\n", i);
            } else
                printf("\tNumber of IP Adapter Prefix entries: 0\n");

            printf("\n");

            pCurrAddresses = pCurrAddresses->Next;
        }
    } else {
        printf("Call to GetAdaptersAddresses failed with error: %d\n",
               dwRetVal);
        if (dwRetVal == ERROR_NO_DATA)
            printf("\tNo addresses were found for the requested parameters\n");
        else {

            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);
                if (pAddresses)
                    FREE(pAddresses);
                exit(1);
            }
        }
    }

    if (pAddresses) {
        FREE(pAddresses);
    }

    return 0;
}

Requisitos

   
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho iphlpapi.h
Biblioteca Iphlpapi.lib
DLL Iphlpapi.dll

Confira também

GetIpAddrTable

Heapalloc

Heapfree

Referência de função auxiliar de IP

Página Inicial do Auxiliar de IP

IP_ADAPTER_ADDRESSES

MIB_IPADDRTABLE

SOCKET_ADDRESS

Windows Sockets