estrutura ADDRINFOEX4 (ws2def.h)
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 addrinfoex4 {
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 addrinfoex4 *ai_next;
int ai_version;
PWSTR ai_fqdn;
int ai_interfaceindex;
HANDLE ai_resolutionhandle;
} ADDRINFOEX4, *PADDRINFOEX4, *LPADDRINFOEX4;
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 |
|---|---|
|
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 GetAddrInfoEx 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 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. |
|
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 para 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. 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.
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 posterior 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. Essa opção só tem suporte no Windows Vista e posterior para o namespace NS_EMAIL . |
|
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 eventualmente foi resolvido será retornado. 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 posterior. |
|
Indica que o objeto atual é estendido: ou seja, um addrinfoex2 ou superior.
Essa opção tem suporte em Windows 8.1, Windows Server 2012 R2 e posteriores. |
|
Um identificador de resolução é retornado no membro ai_resolutionhandle .
Essa opção tem suporte em Windows 10, Windows Server 2016 e posteriores. |
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 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_INET e PF_INET), 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
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
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
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.
Comentários
A estrutura addrinfoex4 tem suporte em Windows 10 e Windows Server 2016
A estrutura addrinfoex4 é usada pela função GetAddrInfoEx para armazenar informações de endereço do host quando o AI_EXTENDED | AI_FQDN | AI_CANONNAME AI_RESOLUTION_HANDLE | bits são definidos no membro addrinfoex4.ai_flags passado por meio deGetAddrInfoEx.parâmetro hints.
A estrutura addrinfoex4 é uma versão aprimorada da estrutura addrinfoex que pode retornar o nome canônico, o nome de domínio totalmente qualificado para o host e um identificador para o nome de domínio totalmente qualificado. Por sua vez, GetAddrInfoEx é uma versão aprimorada das estruturas addrinfo e addrinfoW usadas com as funções getaddrinfo e GetAddrInfoW . 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.
Os dados de blob em tha ai_blob membro 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.
Quando UNICODE ou _UNICODE é definido, addrinfoex4 é definido como addrinfoex4W, 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 addrinfoex4W é usada.
Quando UNICODE ou _UNICODE não está definido, addrinfoex4 é definido como addrinfoex4A, a versão ANSI dessa estrutura. Os parâmetros de cadeia de caracteres são do tipo de dados char * e a estrutura addrinfoex4A é usada.
Após uma chamada bem-sucedida para GetAddrInfoEx, uma lista vinculada de estruturas addrinfoex4 é 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 addrinfoex4 retornada até que um ponteiro NULL seja encontrado. Em cada estrutura addrinfoex4 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 addrinfoex4 retornada aponta para uma estrutura de endereço de soquete preenchida, cujo comprimento é especificado em seu membro ai_addrlen .
Exemplos
O código a seguir descreve como fazer uma chamada para GetAddrInfoEx com uma estrutura addrinfoex4 para recuperar o identificador para um FQDN. em seguida, o exemplo chama WSAIoctl com a estrutura ASSOCIATE_NAMERES_CONTEXT_INPUT .
//
// Connect to a server using its IPv4 addresses
//
VOID
ConnectServer(
PCWSTR server)
{
int iResult;
PADDRINFOEX4 pResult = NULL;
ADDRINFOEX3 hints = { 0 };
PADDRINFOEX4 pCur = NULL;
WSADATA wsaData;
SOCKET connectSocket = INVALID_SOCKET;
ULONG bytesReturned = 0;
ASSOCIATE_NAMERES_CONTEXT_INPUT input = { 0 };
SOCKADDR_IN clientService;
wchar_t ipstringbuffer[46];
String string;
DWORD dwRetval;
//
// Initialize Winsock
//
iResult = WSAStartup(
MAKEWORD(2, 2),
&wsaData);
if (iResult != 0) {
printf("WSAStartup failed: %d\n", iResult);
goto Exit;
}
//
// Create a SOCKET for connection
//
connectSocket = socket(
AF_UNSPEC,
SOCK_STREAM,
IPPROTO_TCP);
if (connectSocket == INVALID_SOCKET)
{
printf("socket failed: %d\n", WSAGetLastError());
goto Exit;
}
//
// Do name resolution
//
hints.ai_family = AF_INET;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags = AI_EXTENDED | AI_FQDN | AI_CANONNAME | AI_RESOLUTION_HANDLE;
hints.ai_version = ADDRINFOEX_VERSION_4;
dwRetval = GetAddrInfoExW(
server,
NULL,
NS_DNS,
NULL,
(const ADDRINFOEXW*)&hints,
(PADDRINFOEXW*)&pResult,
NULL,
NULL,
NULL, NULL);
if (dwRetval != 0) {
printf("GetAddrInfoEx failed with error: %d\n", dwRetval);
goto Exit;
}
input.TransportSettingId.Guid = ASSOCIATE_NAMERES_CONTEXT;
input.Handle = pResult->ai_resolutionhandle;
//
// Associate socket with the handle
//
if (WSAIoctl(
connectSocket,
SIO_APPLY_TRANSPORT_SETTING,
(VOID *)&input,
sizeof(input),
NULL,
0,
&bytesReturned,
NULL,
NULL) == SOCKET_ERROR)
if (iResult != 0){
printf("WSAIoctl failed: %d\n", WSAGetLastError());
goto Exit;
}
//
// Connect to server
//
pCur = pResult;
while (pCur != NULL)
{
if (pCur->ai_addr->sa_family == AF_INET)
{
clientService = *(const sockaddr_in*)pCur->ai_addr;
clientService.sin_port = htons(80);
if (connect(
connectSocket,
(const SOCKADDR *)&clientService,
sizeof(clientService)) == SOCKET_ERROR)
{
printf("connect failed: %d\n", WSAGetLastError());
goto Exit;
}
}
pCur = pCur->ai_next;
}
Exit:
if (connectSocket != INVALID_SOCKET)
{
closesocket(connectSocket);
}
if (pResult)
{
FreeAddrInfoExW((ADDRINFOEXW*)pResult);
}
WSACleanup();
return;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 10 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2016 [somente aplicativos da área de trabalho] |
| Cabeçalho | ws2def.h |