Estrutura ADDRINFOW (ws2def.h)
A estrutura addrinfoW é usada pela função GetAddrInfoW para armazenar informações de endereço do host.
Sintaxe
typedef struct addrinfoW {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
PWSTR ai_canonname;
struct sockaddr *ai_addr;
struct addrinfoW *ai_next;
} ADDRINFOW, *PADDRINFOW;
Membros
ai_flags
Tipo: int
Sinalizadores que indicam as opções usadas na função GetAddrInfoW .
Os valores com suporte para o membro ai_flags são definidos no arquivo de cabeçalho Winsock2.h e podem ser uma combinação das opções listadas na tabela 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 GetAddrInfoW deve ser uma cadeia de caracteres numérica. |
|
Se esse bit for 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 GetAddrInfoW 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 só tem suporte no Windows Vista e posterior. |
|
Se a solicitação GetAddrInfoW 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 posterior 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 posterior 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 posterior para o namespace NS_EMAIL . |
|
Se um nome simples (rótulo único) for especificado, GetAddrInfoW 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 bits 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 GetAddrInfoW 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. |
|
Desabilite a codificação automática de Nome de Domínio Internacional usando Punycode nas funções de resolução de nomes chamadas pela função GetAddrInfoW .
Essa opção tem suporte em Windows 8, Windows Server 2012 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 Windows Vista e posterior, 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 no Winsock2.h e nunca deve ser usado diretamente.
Os valores com suporte no momento são AF_INET ou AF_INET6, que são os formatos de família de endereços da Internet para IPv4 e IPv6. Outras opções para 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 PF_ constantes da família de protocolos são idênticos (por exemplo, AF_UNSPEC e PF_UNSPEC), portanto, qualquer constante pode 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 inclusão 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 em Winsock2.h e nos arquivos de cabeçalho Wsrm.h .
Na SDK do Windows lançada para o Windows Vista e posterior, 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: PWSTR
O nome canônico do host.
ai_addr
Tipo: struct sockaddr*
Um ponteiro para uma estrutura sockaddr . O membro ai_addr em cada estrutura ADDRINFOW retornada aponta para uma estrutura de endereço de soquete preenchida. O comprimento, em bytes, de cada estrutura ADDRINFOW retornada é especificado no membro ai_addrlen .
ai_next
Tipo: struct addrinfoW*
Um ponteiro para a próxima estrutura em uma lista vinculada. Esse parâmetro é definido como NULL na última estrutura addrinfoW de uma lista vinculada.
Comentários
A estrutura addrinfoW é usada pela função GetAddrInfoW unicode para armazenar informações de endereço do host.
A estrutura addrinfo é a versão ANSI dessa estrutura usada pela função getaddrinfo ANSI.
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 é definido, ADDRINFOT é definido como a estrutura addrinfoW e GetAddrInfo é definido como GetAddrInfoW, a versão Unicode dessa função. 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.
Após uma chamada bem-sucedida para GetAddrInfoW, uma lista vinculada de estruturas ADDRINFOW é retornada no parâmetro ppResult passado para a função GetAddrInfoW . A lista pode ser processada seguindo o ponteiro fornecido no membro ai_next de cada estrutura ADDRINFOW retornada até que um ponteiro NULL seja encontrado. Em cada estrutura ADDRINFOW 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 ADDRINFOW retornada aponta para uma estrutura de endereço de soquete preenchida, cujo comprimento é especificado em seu membro ai_addrlen .
Exemplos
O exemplo de código a seguir mostra como usar a estrutura addrinfoW .
#ifndef UNICODE
#define UNICODE
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#pragma comment(lib, "Ws2_32.lib")
int __cdecl wmain(int argc, wchar_t ** argv)
{
//--------------------------------
// Declare and initialize variables.
WSADATA wsaData;
int iResult;
ADDRINFOW *result = NULL;
ADDRINFOW *ptr = NULL;
ADDRINFOW hints;
DWORD dwRetval = 0;
int i = 1;
struct sockaddr_in *sockaddr_ipv4;
struct sockaddr_in6 *sockaddr_ipv6;
// LPSOCKADDR sockaddr_ip;
wchar_t ipstringbuffer[46];
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
wprintf(L" provides protocol-independent translation\n");
wprintf(L" from a host name to an IP address\n");
wprintf(L"%ws example usage\n", argv[0]);
wprintf(L" %ws www.contoso.com 0\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
wprintf(L"WSAStartup failed: %d\n", iResult);
return 1;
}
//--------------------------------
// Setup the hints address info structure
// which is passed to the GetAddrInfoW() function
memset(&hints, 0, sizeof (hints));
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
wprintf(L"Calling GetAddrInfoW with following parameters:\n");
wprintf(L"\tName = %ws\n", argv[1]);
wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrInfoW(). If the call succeeds,
// the aiList variable will hold a linked list
// of addrinfo structures containing response
// information about the host
dwRetval = GetAddrInfoW(argv[1], argv[2], &hints, &result);
if (dwRetval != 0) {
wprintf(L"GetAddrInfoW failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
wprintf(L"GetAddrInfoW returned success\n");
// Retrieve each address and print out the hex bytes
for (ptr = result; ptr != NULL; ptr = ptr->ai_next) {
wprintf(L"GetAddrInfoW response %d\n", i++);
wprintf(L"\tFlags: 0x%x\n", ptr->ai_flags);
wprintf(L"\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
wprintf(L"Unspecified\n");
break;
case AF_INET:
wprintf(L"AF_INET (IPv4)\n");
// the InetNtop function is available on Windows Vista and later
sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
wprintf(L"\tIPv4 address %ws\n",
InetNtop(AF_INET, &sockaddr_ipv4->sin_addr, ipstringbuffer,
46));
// We could also use the WSAAddressToString function
// 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)
// wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
// else
// wprintf(L"\tIPv4 address %ws\n", ipstringbuffer);
break;
case AF_INET6:
wprintf(L"AF_INET6 (IPv6)\n");
// the InetNtop function is available on Windows Vista and later
sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
wprintf(L"\tIPv6 address %ws\n",
InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr,
ipstringbuffer, 46));
// We could also use WSAAddressToString which also returns the scope ID
// 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)
// wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
//else
// wprintf(L"\tIPv6 address %ws\n", ipstringbuffer);
break;
default:
wprintf(L"Other %ld\n", ptr->ai_family);
break;
}
wprintf(L"\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
wprintf(L"Unspecified\n");
break;
case SOCK_STREAM:
wprintf(L"SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
wprintf(L"SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
wprintf(L"SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
wprintf(L"SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
wprintf(L"SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_socktype);
break;
}
wprintf(L"\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
wprintf(L"Unspecified\n");
break;
case IPPROTO_TCP:
wprintf(L"IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
wprintf(L"IPPROTO_UDP (UDP) \n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_protocol);
break;
}
wprintf(L"\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
wprintf(L"\tCanonical name: %s\n", ptr->ai_canonname);
}
FreeAddrInfo(result);
WSACleanup();
return 0;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista, Windows XP com SP2 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Cabeçalho | ws2def.h (inclua Windows Server 2012, Windows 7 Windows Server 2008 R2) |