Estrutura ADDRINFOEXW (ws2def.h)
A estrutura addrinfoex é usada pela função GetAddrInfoEx para armazenar informações de endereço do host.
Sintaxe
typedef struct addrinfoexW {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
PWSTR ai_canonname;
struct sockaddr *ai_addr;
void *ai_blob;
size_t ai_bloblen;
LPGUID ai_provider;
struct addrinfoexW *ai_next;
} ADDRINFOEXW, *PADDRINFOEXW, *LPADDRINFOEXW;
Membros
ai_flags
Tipo: int
Sinalizadores que indicam opções usadas na função GetAddrInfoEx .
Os valores com suporte para o membro ai_flags são definidos no arquivo de inclusão Winsock2.h e 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 .
Quando os bits AI_CANONNAME e AI_FQDN são definidos, uma estrutura addrinfoex2 é retornada e não a estrutura addrinfoex . |
|
O parâmetro nodename passado para a função GetAddrInfoEx 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 GetAddrInfoEx 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 GetAddrInfoEx 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 são de resultados não autoritativos.
Quando essa opção é definida no parâmetro pHints de GetAddrInfoEx, o provedor de namespace NS_EMAIL retorna resultados autoritativos e não autoritativos. Se essa opção não estiver definida, somente os resultados autoritativos serão retornados. No parâmetro ppResults retornado por GetAddrInfoEx, esse sinalizador é definido no membro ai_flags da estrutura addrinfoex para resultados não autoritativos. 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. Se o bit AI_SECURE estiver definido, o provedor de namespace NS_EMAIL retornará os resultados obtidos com segurança aprimorada para minimizar possíveis falsificações.
Quando essa opção é definida no parâmetro pHints de GetAddrInfoEx, o provedor de namespace NS_EMAIL retorna apenas os resultados obtidos com segurança aprimorada para minimizar possíveis falsificações. No parâmetro ppResults retornado por GetAddrInfoEx, esse sinalizador é definido no membro ai_flags da estrutura addrinfoex para resultados retornados com segurança aprimorada para minimizar possíveis falsificações. 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 nomes preferenciais para publicação com um namespace específico.
Quando essa opção é definida no parâmetro pHints de GetAddrInfoEx, nenhum nome deve ser fornecido no parâmetro pName e o provedor de namespace NS_EMAIL retornará nomes preferenciais para publicação. No parâmetro ppResults retornado por GetAddrInfoEx, esse sinalizador é definido no membro ai_flags da estrutura addrinfoex para resultados retornados para nomes preferenciais para publicação. Essa opção só tem suporte no Windows Vista e posteriores para o namespace NS_EMAIL . |
|
O nome de domínio totalmente qualificado é retornado no primeiro membro ai_canonicalname .
Quando essa opção é definida no parâmetro pHints de GetAddrInfoEx e um nome simples (rótulo único) é especificado no parâmetro pName , o nome de domínio totalmente qualificado para o qual o nome acabou sendo resolvido será retornado. Quando os bits AI_CANONNAME e AI_FQDN são definidos, uma estrutura addrinfoex2 é retornada e não a estrutura addrinfoex . 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 GetAddrInfoEx .
Essa opção tem suporte em Windows 8, Windows Server 2012 e posteriores. |
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 inclusão 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 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 e 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 (Protocolo de Datagrama do Usuário) 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 de protocolo multicast PGM (Pragmática Geral Multicast) no Windows, geralmente conhecida como programação multicast confiável. |
|
Fornece um pacote pseudo stream 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 forem 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 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 no 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: PCTSTR
O nome canônico do host.
ai_addr
Tipo: struct sockaddr*
Um ponteiro para uma estrutura sockaddr . O membro ai_addr em cada estrutura addrinfoex retornada aponta para uma estrutura de endereço de soquete preenchida. O comprimento, em bytes, de cada estrutura addrinfoex retornada é especificado no membro ai_addrlen .
ai_blob
Tipo: void*
Um ponteiro para dados usados para retornar informações de namespace específicas do provedor associadas ao nome além de uma lista de endereços. O comprimento, em bytes, do buffer apontado por ai_blob deve ser especificado no membro ai_bloblen .
ai_bloblen
Tipo: size_t
O comprimento, em bytes, do membro ai_blob .
ai_provider
Tipo: LPGUID
Um ponteiro para o GUID de um provedor de namespace específico.
ai_next
Tipo: struct addrinfoex*
Um ponteiro para a próxima estrutura em uma lista vinculada. Esse parâmetro é definido como NULL na última estrutura addrinfoex de uma lista vinculada.
Comentários
A estrutura addrinfoex é usada pela função GetAddrInfoEx para armazenar informações de endereço do host. A estrutura addrinfoex é uma versão aprimorada das estruturas addrinfo e addrinfoW . Os membros de estrutura extra são para dados de blob e o GUID para o provedor de namespace. Os dados de blob são usados para retornar informações adicionais de namespace específicas do provedor associadas a um nome. O formato de dados no membro ai_blob é específico para um provedor de namespace específico. Atualmente, os dados de blob são usados pelo provedor de namespace NS_EMAIL para fornecer informações adicionais.
A estrutura addrinfoex é uma versão aprimorada da estrutura addrinfo e addrinfoW usada com a função GetAddrInfoEx . A função GetAddrInfoEx permite especificar o provedor de namespace para resolve a consulta. Para uso com o protocolo IPv6 e IPv4, a resolução de nomes pode ser pelo DNS (Sistema de Nomes de Domínio), um arquivo de hosts local, um provedor de email (o namespace NS_EMAIL ) ou por outros mecanismos de nomenclatura.
Quando UNICODE ou _UNICODE é definido, addrinfoex é definido como addrinfoexW, a versão Unicode dessa estrutura. Os parâmetros de cadeia de caracteres são definidos para o tipo de dados PWSTR e a estrutura addrinfoexW é usada.
Quando UNICODE ou _UNICODE não está definido, addrinfoex é definido como addrinfoexA, a versão ANSI dessa estrutura. Os parâmetros de cadeia de caracteres são do tipo de dados PCSTR e a estrutura addrinfoexA é usada.
Após uma chamada bem-sucedida para GetAddrInfoEx, uma lista vinculada de estruturas addrinfoex é retornada no parâmetro ppResult passado para a função GetAddrInfoEx . A lista pode ser processada seguindo o ponteiro fornecido no membro ai_next de cada estrutura addrinfoex retornada até que um ponteiro NULL seja encontrado. Em cada estrutura addrinfoex 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 addrinfoex retornada aponta para uma estrutura de endereço de soquete preenchida, cujo comprimento é especificado em seu membro ai_addrlen .
Exemplos
O exemplo a seguir demonstra o uso da estrutura addrinfoex .
#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;
ADDRINFOEX *result = NULL;
ADDRINFOEX *ptr = NULL;
ADDRINFOEX hints;
DWORD dwRetval = 0;
int i = 1;
DWORD dwNamespace = NS_DNS;
LPGUID lpNspid = NULL;
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 GetAddrInfoEx with following parameters:\n");
wprintf(L"\tName = %ws\n", argv[1]);
wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrInfoEx(). If the call succeeds,
// the aiList variable will hold a linked list
// of ADDRINFOEX structures containing response
// information about the host
dwRetval = GetAddrInfoEx(argv[1], argv[2],
dwNamespace, lpNspid, &hints, &result,
NULL, NULL, NULL, NULL);
if (dwRetval != 0) {
wprintf(L"GetAddrInfoEx failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
wprintf(L"GetAddrInfoEx returned success\n");
// Retrieve each address and print out the hex bytes
for (ptr = result; ptr != NULL; ptr = ptr->ai_next) {
wprintf(L"GetAddrInfoEx 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);
}
FreeAddrInfoEx(result);
WSACleanup();
return 0;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Cabeçalho | ws2def.h (inclua Windows Server 2012, Windows 7 Windows Server 2008 R2) |