estrutura ADDRINFOEX6 (ws2def.h)

Artigo
03/20/2023

A estrutura addrinfoex4 é usada pela função GetAddrInfoEx para armazenar informações de endereço do host quando um adaptador de rede específico é solicitado.

Sintaxe

typedef struct addrinfoex6 {
  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;
  GUID                *ai_provider;
  struct addrinfoex5  *ai_next;
  int                 ai_version;
  PWSTR               ai_fqdn;
  int                 ai_interfaceindex;
  HANDLE              ai_resolutionhandle;
  unsigned int        ai_ttl;
  unsigned int        ai_numservers;
  ADDRINFO_DNS_SERVER *ai_servers;
  ULONG64             ai_responseflags;
} ADDRINFOEX6, *PADDRINFOEX6;

Membros

ai_flags

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 .
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 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. 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. 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. 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_fqdn . 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. 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 no Windows 8, Windows Server 2012 e posterior.
AI_EXTENDED 0x80000000	Indica que o objeto atual é estendido: ou seja, um addrinfoex2 ou superior. Essa opção é compatível com Windows 8.1, Windows Server 2012 R2 e posterior.
AI_RESOLUTION_HANDLE 0x40000000	Um identificador de resolução é retornado no membro ai_resolutionhandle . Essa opção tem suporte no Windows 10, Windows Server 2016 e posterior.
AI_RETURN_TTL 0x0080	O número de segundos para os quais o registro DNS é válido. Se esse sinalizador estiver presente, o GetAddrInfoEx. O parâmetro ppResult retornará uma lista de estruturas addrinfoex5 , em que o membro ai_ttl conterá o TTL individual do registro DNS.
AI_EXCLUSIVE_CUSTOM_SERVERS 0x0080	Por padrão, os servidores especificados no membro ai_servers são usados como fallback para os servidores DNS do sistema. Se essa opção for especificada, a consulta DNS usará os servidores personalizados especificados em ai_server exclusivamente.
AI_RETURN_RESPONSE_FLAGS 0x0080	Solicita informações extras sobre os resultados do DNS. Se esse sinalizador estiver presente, o parâmetro GetAddrInfoExppResult retornará uma lista de estruturas addrinfoex6 , em que o membro ai_responseflags conterá informações sobre a origem dos resultados do DNS.

ai_family

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 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_INET e PF_INET), 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.

ai_socktype

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 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 (User Datagram Protocol) 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 do protocolo multicast PGM (Pragmática Geral Multicast) no Windows, geralmente conhecida como programação multicast confiável.
SOCK_SEQPACKET 5	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

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 .

No SDK do Windows lançado 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 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.

Valor	Significado
IPPROTO_TCP 6	O Protocolo de Controle de Transmissão (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 (Protocolo de Datagrama do Usuário). 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

O comprimento, em bytes, do buffer apontado pelo membro ai_addr .

ai_canonname

O nome canônico do host.

ai_addr

Um ponteiro para uma estrutura sockaddr . O membro ai_addr em cada estrutura addrinfoex4 retornada aponta para uma estrutura de endereço de soquete preenchida. O comprimento, em bytes, de cada estrutura addrinfoex4 retornada é especificado no membro ai_addrlen .

ai_blob

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

O comprimento, em bytes, do membro ai_blob .

ai_provider

Um ponteiro para o GUID de um provedor de namespace específico.

ai_next

Um ponteiro para a próxima estrutura em uma lista vinculada. Esse parâmetro é definido como NULL na última estrutura addrinfoex4 de uma lista vinculada.

ai_version

O número de versão dessa estrutura. O valor usado atualmente para esta versão da estrutura é 4.

ai_fqdn

O nome de domínio totalmente qualificado para o host.

ai_interfaceindex

O índice de interface, conforme definido pelo IP_ADAPTER_ADDRESSES. Propriedade IfIndex retornada em GetAdaptersAddresses.

ai_resolutionhandle

Identificador apontando para o nome de domínio totalmente qualificado para o host.

ai_ttl

Número de segundos para os quais esse registro DNS é válido.

ai_numservers

Número de servidores DNS personalizados presentes no membro ai_servers .

ai_servers

Uma matriz de N (em que N == ai_numservers) ADDRINFO_DNS_SERVER objetos. Se ai_numservers for 0, ai_servers deverá ser NULL.

ai_responseflags

Retorna um bitmap que contém qualquer um dos valores a seguir.

Constante	Valor	Significado
AI_DNS_RESPONSE_SECURE	0x1	A resposta veio de protocolos seguros, como DNS-over-HTTPS.
AI_DNS_RESPONSE_HOSTFILE	0x2	A resposta veio do arquivo de hosts .

Comentários

A estrutura ADDRINFOEX6 é uma extensão da estrutura ADDRINFOEX5 . Além de todos os campos da estrutura ADDRINFOEX5 , ele contém os membros ai_numservers e ai_servers , permitindo o uso de servidores DNS personalizados por consulta. Ele também contém o membro ai_responseflags , que contém informações sobre a origem das respostas DNS.

Se o sinalizador AI_RETURN_RESPONSE_FLAGS estiver presente no membro ai_flags , o parâmetro GetAddrInfoExppResult retornará uma lista de estruturas ADDRINFOEX6 , em que o membro ai_responseflags conterá informações sobre a origem dos resultados do DNS.

Se os membros ai_numservers e ai_servers apontarem para uma matriz de objetos ADDRINFO_DNS_SERVER válidos, a consulta DNS adicionará esses servidores como fallback aos servidores DNS configurados pelo sistema. Se a opção AI_EXCLUSIVE_CUSTOM_SERVERS estiver presente no membro ai_flags , a consulta DNS usará exclusivamente os servidores personalizados.