Estrutura ADDRINFOA (ws2def.h)
A estrutura addrinfo é usada pela função getaddrinfo para armazenar informações de endereço do host.
Sintaxe
typedef struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char *ai_canonname;
struct sockaddr *ai_addr;
struct addrinfo *ai_next;
} ADDRINFOA, *PADDRINFOA;
Membros
ai_flags
Tipo: int
Sinalizadores que indicam opções usadas na função getaddrinfo .
Os valores com suporte para o membro ai_flags são definidos no arquivo de cabeçalho Ws2def.h no SDK do Windows para Windows 7 e posterior. Esses valores são definidos no arquivo de cabeçalho Ws2tcpip.h no SDK do Windows para Windows Server 2008 e Windows Vista. Esses valores são definidos no arquivo de cabeçalho Ws2tcpip.h no SDK da Plataforma para Windows Server 2003 e no Windows XP. Os valores com suporte para o membro ai_flags podem ser uma combinação das opções a seguir.
| Valor | Significado |
|---|---|
|
O endereço do soquete será usado em uma chamada para a função de associação . |
|
O nome canônico é retornado no primeiro membro ai_canonname . |
|
O parâmetro nodename passado para a função getaddrinfo deve ser uma cadeia de caracteres numérica. |
|
Se esse bit estiver definido, uma solicitação será feita para endereços IPv6 e endereços IPv4 com AI_V4MAPPED.
Essa opção tem suporte no Windows Vista e posterior. |
|
O getaddrinfo só resolve se um endereço global estiver configurado. O endereço de loopback IPv6 e IPv4 não é considerado um endereço global válido.
Essa opção tem suporte no Windows Vista e posterior. |
|
Se a solicitação getaddrinfo para endereços IPv6 falhar, uma solicitação de serviço de nome será feita para endereços IPv4 e esses endereços serão convertidos em formato de endereço IPv6 mapeado por IPv4.
Essa opção tem suporte no Windows Vista e posterior. |
|
As informações de endereço podem ser de um provedor de namespace não autoritativo.
Essa opção só tem suporte no Windows Vista e posteriores para o namespace NS_EMAIL . |
|
As informações de endereço são de um canal seguro.
Essa opção só tem suporte no Windows Vista e posteriores para o namespace NS_EMAIL . |
|
As informações de endereço são para um nome preferencial para um usuário.
Essa opção só tem suporte no Windows Vista e posteriores para o namespace NS_EMAIL . |
|
Se um nome simples (rótulo único) for especificado, getaddrinfo retornará o nome de domínio totalmente qualificado para o qual o nome acabou sendo resolvido. O nome de domínio totalmente qualificado é retornado no membro ai_canonname .
Isso é diferente de AI_CANONNAME sinalizador de bit que retorna o nome canônico registrado no DNS que pode ser diferente do nome de domínio totalmente qualificado para o qual o nome simples foi resolvido. Somente um dos bits AI_FQDN e AI_CANONNAME pode ser definido. A função getaddrinfo falhará se ambos os sinalizadores estiverem presentes com EAI_BADFLAGS. Essa opção tem suporte no Windows 7, Windows Server 2008 R2 e posterior. |
|
Uma dica para o provedor de namespace de que o nome do host que está sendo consultado está sendo usado em um cenário de compartilhamento de arquivos. O provedor de namespace pode ignorar essa dica.
Essa opção tem suporte no Windows 7, Windows Server 2008 R2 e posterior. |
ai_family
Tipo: int
A família de endereços. Os valores possíveis para a família de endereços são definidos no arquivo de cabeçalho Winsock2.h .
Na SDK do Windows lançada para o Windows Vista e posteriores, a organização dos arquivos de cabeçalho foi alterada e os valores possíveis para a família de endereços são definidos no arquivo de cabeçalho Ws2def.h. Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente em Winsock2.h e nunca deve ser usado diretamente.
Atualmente, os valores compatíveis são AF_INET ou AF_INET6, que são os formatos da família de endereços da Internet para IPv4 e IPv6. Outras opções para a família de endereços (AF_NETBIOS para uso com NetBIOS, por exemplo) têm suporte se um provedor de serviços do Windows Sockets para a família de endereços estiver instalado. Observe que os valores para a família de endereços AF_ e as constantes da família de protocolos PF_ são idênticos (por exemplo, AF_UNSPEC e PF_UNSPEC), para que qualquer constante possa ser usada.
A tabela a seguir lista valores comuns para a família de endereços, embora muitos outros valores sejam possíveis.
ai_socktype
Tipo: int
O tipo de soquete. Os valores possíveis para o tipo de soquete são definidos no arquivo de cabeçalho Winsock2.h .
A tabela a seguir lista os valores possíveis para o tipo de soquete compatível com o Windows Sockets 2:
| Valor | Significado |
|---|---|
|
Fornece fluxos de bytes sequenciados, confiáveis, bidirecionais baseados em conexão com um mecanismo de transmissão de dados OOB. Usa o protocolo TCP para a família de endereços da Internet (AF_INET ou AF_INET6). Se o membro ai_family for AF_IRDA, SOCK_STREAM será o único tipo de soquete com suporte. |
|
Possui suporte para datagramas, que são pacotes sem conexão e não confiáveis de um comprimento máximo fixo (normalmente pequeno). Usa o UDP (User Datagram Protocol) para a família de endereços da Internet (AF_INET ou AF_INET6). |
|
Fornece um soquete bruto que permite que um aplicativo manipule o próximo cabeçalho de protocolo de camada superior. Para manipular o cabeçalho IPv4, a opção de soquete IP_HDRINCL deve ser definida no soquete. Para manipular o cabeçalho IPv6, a opção de soquete IPV6_HDRINCL deve ser definida no soquete. |
|
Fornece um datagrama de mensagem confiável. Um exemplo desse tipo é a implementação do protocolo multicast PGM (Pragmática Geral Multicast) no Windows, geralmente conhecida como programação multicast confiável. |
|
Fornece um pacote pseudo-fluxo com base em datagramas. |
No Windows Sockets 2, novos tipos de soquete foram introduzidos. Um aplicativo pode descobrir dinamicamente os atributos de cada protocolo de transporte disponível por meio da função WSAEnumProtocols . Portanto, um aplicativo pode determinar as possíveis opções de tipo de soquete e protocolo para uma família de endereços e usar essas informações ao especificar esse parâmetro. As definições de tipo de soquete nos arquivos de cabeçalho Winsock2.h e Ws2def.h serão atualizadas periodicamente conforme novos tipos de soquete, famílias de endereços e protocolos são definidos.
No Windows Sockets 1.1, os únicos tipos de soquete possíveis são SOCK_DATAGRAM e SOCK_STREAM.
ai_protocol
Tipo: int
O tipo de protocolo. As opções possíveis são específicas para a família de endereços e o tipo de soquete especificados. Os valores possíveis para o ai_protocol são definidos nos arquivos de cabeçalho Winsock2.h e Wsrm.h .
Na SDK do Windows lançada para o Windows Vista e posteriores, a organização dos arquivos de cabeçalho foi alterada e esse membro pode ser um dos valores do tipo de enumeração IPPROTO definido no arquivo de cabeçalho Ws2def.h. Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente em Winsock2.h e nunca deve ser usado diretamente.
Se um valor de 0 for especificado para ai_protocol, o chamador não deseja especificar um protocolo e o provedor de serviços escolherá o ai_protocol a ser usado. Para protocolos diferentes de IPv4 e IPv6, defina ai_protocol como zero.
A tabela a seguir lista valores comuns para o membro ai_protocol , embora muitos outros valores sejam possíveis.
Se o membro ai_family for AF_IRDA, o ai_protocol deverá ser 0.
ai_addrlen
Tipo: size_t
O comprimento, em bytes, do buffer apontado pelo membro ai_addr .
ai_canonname
Tipo: char*
O nome canônico do host.
ai_addr
Tipo: struct sockaddr*
Um ponteiro para uma estrutura sockaddr . O membro ai_addr em cada estrutura addrinfo retornada aponta para uma estrutura de endereço de soquete preenchida. O comprimento, em bytes, de cada estrutura addrinfo retornada é especificado no membro ai_addrlen .
ai_next
Tipo: struct addrinfo*
Um ponteiro para a próxima estrutura em uma lista vinculada. Esse parâmetro é definido como NULL na última estrutura addrinfo de uma lista vinculada.
Comentários
A estrutura addrinfo é usada pela função getaddrinfo ANSI para armazenar informações de endereço do host.
A estrutura addrinfoW é a versão dessa estrutura usada pela função GetAddrInfoW unicode.
Macros no arquivo de cabeçalho Ws2tcpip.h definem uma estrutura ADDRINFOT e um nome de função de caso misto de GetAddrInfo. A função GetAddrInfo deve ser chamada com os parâmetros nodename e servname de um ponteiro do tipo TCHAR e os parâmetros hints e res de um ponteiro do tipo ADDRINFOT. Quando UNICODE ou _UNICODE não está definido, ADDRINFOT é definido como a estrutura addrinfo e GetAddrInfo é definido como getaddrinfo, a versão ANSI dessa função. Quando UNICODE ou _UNICODE é definido, ADDRINFOT é definido como a estrutura addrinfoW e GetAddrInfo é definido como GetAddrInfoW, a versão Unicode dessa função.
Após uma chamada bem-sucedida para getaddrinfo, uma lista vinculada de estruturas addrinfo é retornada no parâmetro res passado para a função getaddrinfo . A lista pode ser processada seguindo o ponteiro fornecido no membro ai_next de cada estrutura addrinfo retornada até que um ponteiro NULL seja encontrado. Em cada estrutura addrinfo retornada, os membros ai_family, ai_socktype e ai_protocol correspondem aos respectivos argumentos em uma chamada de função de soquete ou WSASocket . Além disso, o membro ai_addr em cada estrutura addrinfo retornada aponta para uma estrutura de endereço de soquete preenchida, cujo comprimento é especificado em seu membro ai_addrlen .
Suporte para getaddrinfo e o struct addrinfo em versões mais antigas do Windows
A função getaddrinfo que usa a estrutura addrinfo foi adicionada ao Ws2_32.dll no Windows XP e posterior. A estrutura addrinfo é definida no arquivo de cabeçalho Ws2tcpip.h incluído com o SDK da Plataforma lançado para Windows XP e posterior e o SDK do Windows lançado para o Windows Vista e posteriores.Para executar um aplicativo que usa a função getaddrinfo e a estrutura addrinfo em versões anteriores do Windows (Windows 2000), você precisa incluir os arquivos Ws2tcpip.h e Wspiapi.h . Quando o arquivo de inclusão Wspiapi.h é adicionado, a função getaddrinfo é definida para a função embutida WspiapiGetAddrInfo no arquivo Wspiapi.h . No runtime, a função WspiapiGetAddrInfo é implementada de forma que, se o Ws2_32.dll ou o Wship6.dll (o arquivo que contém getaddrinfo na Visualização de Tecnologia IPv6 para Windows 2000) não incluir getaddrinfo, uma versão de getaddrinfo será implementada embutida com base no código no arquivo de cabeçalho Wspiapi.h . Esse código embutido será usado em plataformas windows mais antigas que não dão suporte nativo à função getaddrinfo .
O protocolo IPv6 tem suporte no Windows 2000 quando a Visualização de Tecnologia IPv6 para Windows 2000 está instalada. Caso contrário, o suporte a getaddrinfo em versões do Windows anteriores ao Windows XP é limitado à manipulação da resolução de nomes IPv4.
A função GetAddrInfoW que usa a estrutura addrinfoW é a versão Unicode da função getaddrinfo e da estrutura addrinfo associada. A função GetAddrInfoW foi adicionada à Ws2_32.dll no Windows XP com Service Pack 2 (SP2). A função GetAddrInfoW e a estrutura addrinfoW não podem ser usadas em versões do Windows anteriores ao Windows XP com SP2.
Exemplos
O exemplo de código a seguir mostra o uso da estrutura addrinfo .
#undef UNICODE
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// link with Ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
INT iRetval;
DWORD dwRetval;
int i = 1;
struct addrinfo *result = NULL;
struct addrinfo *ptr = NULL;
struct addrinfo hints;
struct sockaddr_in *sockaddr_ipv4;
// struct sockaddr_in6 *sockaddr_ipv6;
LPSOCKADDR sockaddr_ip;
char ipstringbuffer[46];
DWORD ipbufferlength = 46;
// Validate the parameters
if (argc != 3) {
printf("usage: %s <hostname> <servicename>\n", argv[0]);
printf(" provides protocol-independent translation\n");
printf(" from an ANSI host name to an IP address\n");
printf("%s example usage\n", argv[0]);
printf(" %s www.contoso.com 0\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("WSAStartup failed: %d\n", iResult);
return 1;
}
//--------------------------------
// Setup the hints address info structure
// which is passed to the getaddrinfo() function
ZeroMemory( &hints, sizeof(hints) );
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
printf("Calling getaddrinfo with following parameters:\n");
printf("\tnodename = %s\n", argv[1]);
printf("\tservname (or port) = %s\n\n", argv[2]);
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
dwRetval = getaddrinfo(argv[1], argv[2], &hints, &result);
if ( dwRetval != 0 ) {
printf("getaddrinfo failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
printf("getaddrinfo returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
printf("getaddrinfo response %d\n", i++);
printf("\tFlags: 0x%x\n", ptr->ai_flags);
printf("\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
printf("Unspecified\n");
break;
case AF_INET:
printf("AF_INET (IPv4)\n");
sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
printf("\tIPv4 address %s\n",
inet_ntoa(sockaddr_ipv4->sin_addr) );
break;
case AF_INET6:
printf("AF_INET6 (IPv6)\n");
// the InetNtop function is available on Windows Vista and later
// sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
// printf("\tIPv6 address %s\n",
// InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstringbuffer, 46) );
// We use WSAAddressToString since it is supported on Windows XP and later
sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
// The buffer length is changed by each call to WSAAddresstoString
// So we need to set it for each iteration through the loop for safety
ipbufferlength = 46;
iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL,
ipstringbuffer, &ipbufferlength );
if (iRetval)
printf("WSAAddressToString failed with %u\n", WSAGetLastError() );
else
printf("\tIPv6 address %s\n", ipstringbuffer);
break;
case AF_NETBIOS:
printf("AF_NETBIOS (NetBIOS)\n");
break;
default:
printf("Other %ld\n", ptr->ai_family);
break;
}
printf("\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
printf("Unspecified\n");
break;
case SOCK_STREAM:
printf("SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
printf("SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
printf("SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
printf("SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
printf("Other %ld\n", ptr->ai_socktype);
break;
}
printf("\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
printf("Unspecified\n");
break;
case IPPROTO_TCP:
printf("IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
printf("IPPROTO_UDP (UDP) \n");
break;
default:
printf("Other %ld\n", ptr->ai_protocol);
break;
}
printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
printf("\tCanonical name: %s\n", ptr->ai_canonname);
}
freeaddrinfo(result);
WSACleanup();
return 0;
}
Requisitos
| Requisito | Valor |
|---|---|
| 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] |
| Cabeçalho | ws2def.h |