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.
[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.
[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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
Recursos de memória insuficientes estão disponíveis para concluir a operação. |
|
Nenhum endereço foi encontrado para os parâmetros solicitados. |
|
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
Referência de função auxiliar de IP