Função getnameinfo (ws2tcpip.h)
A função getnameinfo fornece resolução de nome independente de protocolo de um endereço para um nome de host ANSI e de um número de porta para o nome do serviço ANSI.
Sintaxe
INT WSAAPI getnameinfo(
[in] const SOCKADDR *pSockaddr,
[in] socklen_t SockaddrLength,
[out] PCHAR pNodeBuffer,
[in] DWORD NodeBufferSize,
[out] PCHAR pServiceBuffer,
[in] DWORD ServiceBufferSize,
[in] INT Flags
);
Parâmetros
[in] pSockaddr
Um ponteiro para uma estrutura de endereço de soquete que contém o endereço e o número da porta do soquete. Para IPv4, o parâmetro sa aponta para uma estrutura de sockaddr_in . Para IPv6, o parâmetro sa aponta para uma estrutura de sockaddr_in6 .
[in] SockaddrLength
O comprimento, em bytes, da estrutura apontada pelo parâmetro sa .
[out] pNodeBuffer
Um ponteiro para uma cadeia de caracteres ANSI usada para manter o nome do host. Em caso de êxito, o nome do host é retornado como um FQDN (Nome de Domínio Totalmente Qualificado) por padrão. Se o parâmetro host for NULL, isso indicará que o chamador não deseja receber uma cadeia de caracteres de nome de host.
[in] NodeBufferSize
O comprimento, em bytes, do buffer apontado pelo parâmetro host . O chamador deve fornecer um buffer grande o suficiente para manter o nome do host, incluindo o caractere NULL de terminação.
[out] pServiceBuffer
Um ponteiro para uma cadeia de caracteres ANSI para manter o nome do serviço. Em caso de êxito, uma cadeia de caracteres ANSI que representa o nome do serviço associado ao número da porta é retornada. Se o parâmetro serv for NULL, isso indicará que o chamador não deseja receber uma cadeia de caracteres de nome de serviço.
[in] ServiceBufferSize
O comprimento, em bytes, do buffer apontado pelo parâmetro serv . O chamador deve fornecer um buffer grande o suficiente para manter o nome do serviço, incluindo o caractere NULL de terminação.
[in] Flags
Um valor usado para personalizar o processamento da função getnameinfo . Consulte a seção Comentários.
Retornar valor
Com êxito, getnameinfo retorna zero. Qualquer valor retornado diferente de zero indica falha e um código de erro específico pode ser recuperado chamando WSAGetLastError.
Códigos de erro não zero retornados pela função getnameinfo também são mapeados para o conjunto de erros descrito pelas recomendações da IETF (Internet Engineering Task Force). A tabela a seguir lista esses códigos de erro e seus equivalentes do WSA. É recomendável que os códigos de erro do WSA sejam usados, pois oferecem informações de erro familiares e abrangentes para programadores Winsock.
| Valor do erro | Equivalente a WSA | Descrição |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | Ocorreu uma falha temporária na resolução de nomes. |
| EAI_BADFLAGS | WSAEINVAL | Um ou mais parâmetros inválidos foram passados para a função getnameinfo . Esse erro será retornado se um nome de host tiver sido solicitado, mas o parâmetro hostlen for zero ou se um nome de serviço tiver sido solicitado, mas o parâmetro servlen for zero. |
| EAI_FAIL | WSANO_RECOVERY | Ocorreu uma falha não detectável na resolução de nomes. |
| EAI_FAMILY | WSAEAFNOSUPPORT | Não há suporte para o membro sa_family da estrutura de endereços de soquete apontada pelo parâmetro sa . |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Ocorreu uma falha de alocação de memória. |
| EAI_NONAME | WSAHOST_NOT_FOUND | Um nome de serviço foi solicitado, mas nenhum número de porta foi encontrado na estrutura apontada pelo parâmetro sa ou nenhum nome de serviço correspondente ao número da porta foi encontrado. NI_NAMEREQD está definido e o nome do host não pode ser localizado ou os parâmetros host e serv eram NULL. |
Use a função gai_strerror para imprimir mensagens de erro com base nos códigos EAI retornados pela função getnameinfo . A função gai_strerror é fornecida para conformidade com as recomendações do IETF, mas não é thread-safe. Portanto, é recomendável usar funções tradicionais do Windows Sockets, como WSAGetLastError .
Além disso, os seguintes códigos de erro podem ser retornados.
| Código do erro | Significado |
|---|---|
| Esse erro será retornado se o parâmetro sa for NULL ou o parâmetro salen for menor que o comprimento necessário para o tamanho da estrutura de sockaddr_in para IPv4 ou a estrutura de sockaddr_in6 para IPv6. |
Comentários
A função getnameinfo é a versão ANSI de uma função que fornece resolução de nome independente de protocolo. A função getnameinfo é usada para traduzir o conteúdo de uma estrutura de endereço de soquete para um nome de nó e/ou um nome de serviço.
Para protocolos IPv6 e IPv4, a resolução de nomes pode ser pelo DNS (Sistema de Nomes de Domínio), um arquivo de hosts local ou por outros mecanismos de nomenclatura. Essa função pode ser usada para determinar o nome do host para um endereço IPv4 ou IPv6, uma pesquisa DNS inversa ou determinar o nome do serviço para um número de porta. A função getnameinfo também pode ser usada para converter um endereço IP ou um número de porta em uma estrutura sockaddr em uma cadeia de caracteres ANSI. Essa função também pode ser usada para determinar o endereço IP de um nome de host.
Outro nome que pode ser usado para a função getnameinfo é GetNameInfoA. Macros no arquivo de cabeçalho Ws2tcpip.h definem GetNameInfoA como getnameinfo.
A versão Unicode dessa função disponível no Windows XP com Service Pack 2 (SP2) e posterior é GetNameInfoW.
Macros no arquivo de cabeçalho Winsock definem um nome de função de maiúsculas e minúsculas de GetNameInfo que pode ser usado quando o aplicativo é direcionado para Windows XP com SP2 e posterior (_WIN32_WINNT >= 0x0502). Essa função GetNameInfo deve ser chamada com os parâmetros host e serv de um ponteiro do tipo TCHAR. Quando UNICODE ou _UNICODE não está definido, GetNameInfo é definido como a versão ANSI e getnameinfo é chamado com os parâmetros host e serv de um ponteiro do tipo char. Quando UNICODE ou _UNICODE é definido, GetNameInfo é definido como a versão Unicode e GetNameInfoW é chamado com os parâmetros pNodeBuffer e pServiceBuffer de um ponteiro do tipo PWCHAR.
Para simplificar a determinação dos requisitos de buffer para os parâmetros host e serv , os valores a seguir para o comprimento máximo do nome do host e o nome máximo do serviço são definidos no arquivo de cabeçalho Ws2tcpip.h .
#define NI_MAXSERV 32
#define NI_MAXHOST 1025
O parâmetro flags pode ser usado para personalizar o processamento da função getnameinfo . Os seguintes sinalizadores estão disponíveis:
- NI_NOFQDN
- NI_NUMERICHOST
- NI_NAMEREQD
- NI_NUMERICSERV
- NI_DGRAM
Quando o sinalizador NI_NAMEREQD é definido, um nome de host que não pode ser resolvido pelo DNS resulta em um erro.
Definir o sinalizador NI_NOFQDN resulta em hosts locais tendo apenas o RDN (Nome Diferenciado Relativo) retornado no parâmetro host .
Definir o sinalizador NI_NUMERICHOST retorna a forma numérica do nome do host em vez de seu nome. A forma numérica do nome do host também será retornada se o nome do host não puder ser resolvido pelo DNS.
Definir o sinalizador NI_NUMERICSERV retorna o número da porta do serviço em vez de seu nome. Além disso, se um nome de host não for encontrado para um endereço IP (127.0.0.2, por exemplo), o nome do host será retornado como o endereço IP.
No Windows Vista e posteriores, se NI_NUMERICSERV não for especificado no parâmetro flags e o número da porta contido na estrutura sockaddr apontada pelo parâmetro sa não resolve a um serviço conhecido, a função getnameinfo retornará a forma numérica do endereço de serviço (o número da porta) como uma cadeia de caracteres numérica. Quando NI_NUMERICSERV é especificado, o número da porta é retornado como uma cadeia de caracteres numérica. Esse comportamento é especificado na seção 6.2 do RFC 3493. Para obter mais informações, consulte www.ietf.org/rfc3493.txt
No Windows Server 2003 e anteriores, se NI_NUMERICSERV não for especificado no parâmetro flags e o número da porta contido na estrutura sockaddr apontada pelo parâmetro sa não resolve a um serviço bem conhecido, a função getnameinfo falhará. Quando NI_NUMERICSERV é especificado, o número da porta é retornado como uma cadeia de caracteres numérica.
Definir o sinalizador NI_DGRAM indica que o serviço é um serviço de datagram. Esse sinalizador é necessário para os poucos serviços que fornecem números de porta diferentes para o serviço UDP e TCP.
Código de exemplo
O exemplo de código a seguir mostra como usar a função getnameinfo .#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData = {0};
int iResult = 0;
DWORD dwRetval;
struct sockaddr_in saGNI;
char hostname[NI_MAXHOST];
char servInfo[NI_MAXSERV];
u_short port = 27015;
// Validate the parameters
if (argc != 2) {
printf("usage: %s IPv4 address\n", argv[0]);
printf(" to return hostname\n");
printf(" %s 127.0.0.1\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("WSAStartup failed: %d\n", iResult);
return 1;
}
//-----------------------------------------
// Set up sockaddr_in structure which is passed
// to the getnameinfo function
saGNI.sin_family = AF_INET;
saGNI.sin_addr.s_addr = inet_addr(argv[1]);
saGNI.sin_port = htons(port);
//-----------------------------------------
// Call getnameinfo
dwRetval = getnameinfo((struct sockaddr *) &saGNI,
sizeof (struct sockaddr),
hostname,
NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);
if (dwRetval != 0) {
printf("getnameinfo failed with error # %ld\n", WSAGetLastError());
return 1;
} else {
printf("getnameinfo returned hostname = %s\n", hostname);
return 0;
}
}
Suporte para getnameinfo em versões mais antigas do Windows
A função getnameinfo foi adicionada ao Ws2_32.dll no Windows XP e posterior. Se você quiser executar um aplicativo usando essa função em versões anteriores do Windows (Windows 2000, Windows NT e Windows Me/98/95), será necessário incluir o arquivo Ws2tcpip.h e também incluir o arquivo Wspiapi.h. Quando o arquivo de inclusão Wspiapi.h é adicionado, a função getnameinfo é definida para a função embutida WspiapiGetNameInfo no arquivo Wspiapi.h . Em runtime, a função WspiapiGetNameInfo é implementada de forma que, se o Ws2_32.dll ou o Wship6.dll (o arquivo que contém getnameinfo na Visualização de Tecnologia IPv6 para Windows 2000) não incluir getnameinfo, uma versão de getnameinfo será implementada embutida com base no código no arquivo de cabeçalho Wspiapi.h . Esse código embutido será usado em plataformas mais antigas do Windows que não dão suporte nativo à função getnameinfo .O protocolo IPv6 tem suporte no Windows 2000 quando a Visualização de Tecnologia IPv6 para Windows 2000 está instalada. Caso contrário, o suporte a getnameinfo em versões do Windows anteriores ao Windows XP está limitado ao tratamento da resolução de nomes IPv4.
A função GetNameInfoW é a versão Unicode de getnameinfo. A função GetNameInfoW foi adicionada ao Ws2_32.dll no Windows XP com SP2. A função GetNameInfoW não pode ser usada em versões do Windows anteriores ao Windows XP com SP2.
Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.
Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | ws2tcpip.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |