Compartilhar via


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
AI_PASSIVE
0x01
O endereço do soquete será usado em uma chamada para a função de associação .
AI_CANONNAME
0x02
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 .

AI_NUMERICHOST
0x04
O parâmetro nodename passado para a função GetAddrInfoEx deve ser uma cadeia de caracteres numérica.
AI_ALL
0x0100
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.

AI_ADDRCONFIG
0x0400
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.

AI_V4MAPPED
0x0800
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.

AI_NON_AUTHORITATIVE
0x04000
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 .

AI_SECURE
0x08000
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 .

AI_RETURN_PREFERRED_NAMES
0x010000
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 .

AI_FQDN
0x00020000
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.

AI_FILESERVER
0x00040000
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_DISABLE_IDN_ENCODING
0x00080000
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.

Valor Significado
AF_UNSPEC
0
A família de endereços não é especificada.
AF_INET
2
A família de endereços IPv4 (Protocolo de Internet versão 4).
AF_NETBIOS
17
A família de endereços NetBIOS. Essa família de endereços só terá suporte se um provedor do Windows Sockets para NetBIOS estiver instalado.
AF_INET6
23
A família de endereços IPv6 (Internet Protocol versão 6).
AF_IRDA
26
A família de endereços irda (Associação de Dados Infravermelhos). Essa família de endereços só terá suporte se o computador tiver uma porta infravermelha e um driver instalados.
AF_BTH
32
A família de endereços Bluetooth. Essa família de endereços só terá suporte se um adaptador Bluetooth estiver instalado no Windows Server 2003 ou posterior.

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
SOCK_STREAM
1
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.
SOCK_DGRAM
2
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).
SOCK_RAW
3
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.
SOCK_RDM
4
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.
SOCK_SEQPACKET
5
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.

Valor Significado
IPPROTO_TCP
6
O protocolo TCP. Esse é um valor possível quando o membro ai_family é AF_INET ou AF_INET6 e o membro ai_socktype é SOCK_STREAM.
IPPROTO_UDP
17
O UDP (User Datagram Protocol). Esse é um valor possível quando o membro ai_family é AF_INET ou AF_INET6 e o parâmetro de tipo é SOCK_DGRAM.
IPPROTO_RM
113
O protocolo PGM para multicast confiável. Esse é um valor possível quando o membro ai_family é AF_INET e o membro ai_socktype é SOCK_RDM. No SDK do Windows lançado para Windows Vista e posterior, esse valor também é chamado de IPPROTO_PGM.
 

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;
}


Nota Verifique se o ambiente de desenvolvimento tem como destino a versão mais recente do Ws2tcpip.h , que inclui definições de estrutura e função para ADDRINFOEX e GetAddrInfoEx, respectivamente.
 

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)

Confira também

GetAddrInfoEx

Addrinfo

addrinfoW