getaddrinfo

9/8/2008

Essa função fornece tradução independente de protocolo de nome do host ao endereço.

Syntax

int getaddrinfo(
  const char FAR* nodename,
  const char FAR* servname,
  const struct addrinfo FAR* hints,
  struct addrinfo FAR* FAR* res
);

Parameters

• NodeName
  [no] Ponteiro para uma NULL-finalizada seqüência de caracteres contendo um nome hospedar (nó) ou um seqüência de caracteres endereço numérico hospedar. O seqüência de caracteres endereço numérico hospedar é um pontilhado-decimal IPv4 endereço ou um hexadecimal IPv6 endereço.

• servname
  [no] Ponteiro para uma NULL-finalizada seqüência de caracteres contendo tanto um serviço nome ou número porta.

• Dicas
  [no] Ponteiro para um addrinfo Oferece suporte a estrutura que fornece dicas sobre o tipo de Soquete o chamador.

• Res
  [out] Ponteiro para uma lista vinculada de um ou mais addrinfo Estruturas contendo informações sobre a hospedar resposta.

Return Value

Essa função retorna zero quando bem-sucedido. O retorno de um diferente de zero código de erro Soquetes do Windows indica falha.

Códigos de erro diferente de zero retornados por essa função também mapa (n.); mapear (v.) para o conjunto de erros descrita por recomendações IETF. A seguinte tabela mostra esses códigos de erro e seus equivalentes WSA *. A seguinte tabela mostra os códigos de erro WSA *. É recomendável que esses códigos de erro WSA * sejam usados, como eles oferecem familiar e abrangente informações de erro para programadores Soquetes do Windows.

Código de erro	Equivalente WSA*	Descrição
EAI_AGAIN	WSATRY_AGAIN	Falha temporária em resolução de nomes.
EAI_BADFLAGS	WSAEINVAL	Valor inválido para ai_flags.
EAI_FAIL	WSANO_RECOVERY	Falha não recuperável no resolução de nomes.
EAI_FAMILY	WSAEAFNOSUPPORT	O ai_family membro não é com suporte.
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	Falha alocação de memória.
EAI_NODATA	WSANO_DATA	Nenhum associado endereço com NodeName.
EAI_NONAME	WSAHOST_NOT_FOUND	Nem NodeName Nem servname fornecido ou não conhecido.
EAI_SERVICE	WSATYPE_NOT_FOUND	O servname parâmetro não é com suporte para ai_socktype.

Remarks

Uma ou ambas as NodeName Ou servname Os parâmetros devem apontar para um NULL-finalizada seqüência de caracteres; Geralmente, ambos são fornecidos.

O número máximo de endereços retornado ao tentar resolver um nome é 15.

Ao sucesso, uma lista vinculada do addrinfo Estruturas é retornado na Res parâmetro; a lista pode ser processada pelo seguinte o ponteiro fornecido na ai_next membro de cada retornado addrinfo estrutura até uma NULL ponteiro for encontrado. Em cada retornado addrinfo estrutura, a ai_family, ai_socktype, e ai_protocol Membros corresponder a respectivos argumentos em uma Soquete (Soquetes do Windows) chamada de função. Além disso, o ai_addr membro em cada retornado addrinfo estrutura aponta para uma estrutura endereço Soquete filled-in, o comprimento dos quais é especificado no seu ai_addrlen membro.

Os chamadores das getaddrinfo função pode fornecer dicas sobre o tipo de Soquete com suporte por um addrinfo estrutura apontado pelo Dicas parâmetro. Quando o Dicas parâmetro for usado, aplicar regras para seu associado addrinfo estrutura. A seguinte lista mostra as regras que aplicar:

• Um valor de PF_UNSPEC para ai_family Indica o chamador irá aceitar qualquer família protocolo.
• Um valor de zero para ai_socktype Indica o chamador irá aceitar qualquer tipo Soquete.
• Um valor de zero para ai_protocol Indica o chamador irá aceitar qualquer protocolo.
• ai_addrlen Deve ser zero ou um NULL ponteiro
• ai_canonname Deve ser zero ou um NULL ponteiro
• ai_addr Deve ser zero ou um NULL ponteiro
• ai_next Deve ser zero ou um NULL ponteiro

Outros valores de addrinfo estrutura fornecida a Dicas parâmetro indicar requisitos específicos. De exemplo, se o chamador trata apenas TCP e não UDP, identificador de ai_socktype membro deve ser definido como SOCK_STREAM. Para outro exemplo, se o chamador trata apenas IPv4 e faz não identificador IPv6, a ai_family membro deve ser definido como PF_INET.

Se a pasta Dicas parâmetro é um NULL ponteiro, a getaddrinfo função trata como se o addrinfo estrutura no Dicas foi inicializado com seus ai_family membro definido como PF_UNSPEC e todos os outros membros definido como zero.

Uso de ai_flags in a Dicas parâmetro

A seguinte tabela mostra os sinalizadores in a ai_flags membro do opcional addrinfo estrutura fornecida a Dicas parâmetro.

Sinalizador	Descrição
AI_PASSIVE	Se definido, este sinalizador indica o chamador pretende usar a estrutura endereço de soquete retornados em uma chamar para o BIND (Soquetes do Windows) função. Se este sinalizador estiver definido e NodeName é um NULL ponteiro, o IP parte endereço da do endereço Soquete estrutura é definida como INADDR_ANY para endereços IPv4 e endereços IN6ADDR_ANY_INIT para IPv6. Se este sinalizador não estiver definida, a estrutura endereço Soquete retornado está pronta para um chamar para o conectar (Soquetes do Windows) função de um protocolo Connection-Oriented ou pronto para um chamar para o conectar (Soquetes do Windows), SendTo, ou Enviar funções de Uma sem conexão protocolo. Se a pasta NodeName parâmetro é um NULL ponteiro neste maiúsculas e minúsculas, a parte endereço IP da estrutura de endereço de soquete é definida como endereço de auto-retorno.
AI_CANONNAME	Se este sinalizador estiver definido e o getaddrinfo função retorna êxito, o ai_canonname membro in a Dicas parâmetro aponta para um NULL-finalizada seqüência de caracteres que contém a nome canônico do nó especificado. Observação O gettaddrinfo função pode retornar com êxito quando o sinalizador AI_CANNONNAME for definida, mas o ai_canonname membro de associado addrinfo estrutura é NULL.Portanto, o uso recomendado do sinalizador de AI_CANONNAME inclui testes se a ai_canonname membro de associado addrinfo estrutura é NULL.
AI_NUMERICHOST	Se este sinalizador estiver definido, o NodeName parâmetro deve conter um não-NULL hospedar numérico endereço seqüência de caracteres, caso contrário será retornado o Erro EAI_NONAME. Isso impede que um serviço resolução de nomes que está sendo chamado; Todas as informações retornadas pelo getaddrinfo função é alocada dinamicamente.

Se nem AI_CANONNAME AI_NUMERICHOST for usado, o getaddrinfo função tentativas resolução. Se um seqüência de caracteres literal é passado getaddrinfo tenta converter o seqüência de caracteres, e se um nome do host é passado a getaddrinfo função tenta resolvê-lo.

Liberando informações de endereço a partir de alocação dinâmica

Todas as informações retornadas pelo getaddrinfo função é alocada dinamicamente, incluindo todas as addrinfo estruturas, estruturas endereço de soquete e nome do host canônico seqüências de caracteres apontada pelo addrinfo estruturas. Para retornar que informações para o sistema, chamar o freeaddrinfo função.

Requirements

Header	ws2tcpip.h
Library	Ws2.lib
Windows Embedded CE	Windows CE .NET 4.1 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

bind (Windows Sockets)
connect (Windows Sockets)
send
sendto
socket (Windows Sockets)
addrinfo
freeaddrinfo
WSAGetLastError