Função GetNameInfoW (ws2tcpip.h)

Artigo
08/28/2023

A função GetNameInfoW fornece resolução de nome independente de protocolo de um endereço para um nome de host Unicode e de um número de porta para o nome do serviço Unicode.

Sintaxe

INT WSAAPI GetNameInfoW(
  [in]  const SOCKADDR *pSockaddr,
  [in]  socklen_t      SockaddrLength,
  [out] PWCHAR         pNodeBuffer,
  [in]  DWORD          NodeBufferSize,
  [out] PWCHAR         pServiceBuffer,
  [in]  DWORD          ServiceBufferSize,
  [in]  INT            Flags
);

Parâmetros

[in] pSockaddr

Um ponteiro para uma estrutura de endereços de soquete que contém o endereço IP e o número da porta do soquete. Para IPv4, o parâmetro pSockaddr aponta para uma estrutura sockaddr_in . Para IPv6, o parâmetro pSockaddr aponta para uma estrutura sockaddr_in6 .

[in] SockaddrLength

O comprimento, em bytes, da estrutura apontada pelo parâmetro pSockaddr .

[out] pNodeBuffer

Um ponteiro para uma cadeia de caracteres Unicode para manter o nome do host. Em caso de êxito, um ponteiro para o nome do host Unicode é retornado como um FQDN (Nome de Domínio Totalmente Qualificado) por padrão. Se o parâmetro pNodeBuffer for NULL, isso indicará que o chamador não deseja receber uma cadeia de caracteres de nome de host.

[in] NodeBufferSize

O número de caracteres WCHAR no buffer apontado pelo parâmetro pNodeBuffer . O chamador deve fornecer um buffer grande o suficiente para manter o nome do host Unicode, incluindo o caractere NULL de terminação.

[out] pServiceBuffer

Um ponteiro para uma cadeia de caracteres Unicode para manter o nome do serviço. Em caso de êxito, um ponteiro é retornado para uma cadeia de caracteres Unicode que representa o nome do serviço associado ao número da porta. Se o parâmetro pServiceBuffer for NULL, isso indicará que o chamador não deseja receber uma cadeia de caracteres de nome de serviço.

[in] ServiceBufferSize

O número de caracteres WCHAR no buffer apontado pelo parâmetro pServiceBuffer . O chamador deve fornecer um buffer grande o suficiente para manter o nome do serviço Unicode, incluindo o caractere NULL de terminação.

[in] Flags

Um valor usado para personalizar o processamento da função GetNameInfoW . Consulte a seção Comentários.

Retornar valor

Em caso de êxito, GetNameInfoW 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 GetNameInfoW também são mapeados para o conjunto de erros descrito pelas recomendações da IETF (Internet Engineering Task Force). A tabela a seguir mostra 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 GetNameInfoW . Esse erro será retornado se um nome de host tiver sido solicitado, mas o parâmetro NodeBufferSize for zero ou se um nome de serviço tiver sido solicitado, mas o parâmetro ServiceBufferSize for zero.
EAI_FAIL	WSANO_RECOVERY	Ocorreu uma falha não recuperá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 pSockaddr .
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 pSockaddr 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 pNodeBuffer e pServiceBuffer eram NULL.

Você pode usar a função gai_strerror para imprimir mensagens de erro com base nos códigos EAI retornados pela função GetNameInfoW . A função gai_strerror é fornecida para conformidade com as recomendações de IETF, mas não é thread-safe. Portanto, o uso de funções tradicionais do Windows Sockets, como WSAGetLastError , é recomendado.

Além disso, os códigos de erro a seguir podem ser retornados.

Código do erro	Significado
WSAEFAULT	Esse erro será retornado se o parâmetro pSockaddr for NULL ou o parâmetro SockaddrLength for menor que o comprimento necessário para o tamanho da estrutura de sockaddr_in para IPv4 ou a estrutura sockaddr_in6 para IPv6.

Comentários

A função GetNameInfoW é a versão Unicode de uma função que fornece resolução de nomes independentes de protocolo. A função GetNameInfoW é usada para traduzir o conteúdo de uma estrutura de endereços de soquete para um nome de nó e/ou um nome de serviço.

Para os 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 de DNS reverso ou determinar o nome do serviço para um número de porta. A função GetNameInfoW 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 Unicode. Essa função também pode ser usada para determinar o endereço IP de um nome de host.

A versão ANSI dessa função é getnameinfo.

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 Service Pack 2 (SP2) e posterior (_WIN32_WINNT >= 0x0502). Essa função GetNameInfo deve ser chamada com os parâmetros pNodeBuffer e pServiceBuffer de um ponteiro do tipo TCHAR. Quando UNICODE ou _UNICODE é definido, GetNameInfo é definido como a versão Unicode e GetNameInfoW é chamado com os parâmetros host e serv de um ponteiro do tipo char. Quando UNICODE ou _UNICODE não está definido, GetNameInfo é definido para a versão ANSI e getnameinfo é 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 pNodeBuffer e pServiceBuffer , os seguintes valores para o tamanho máximo do nome do host e o nome máximo do serviço são definidos no arquivo de cabeçalho Ws2tcpip.h :

#include <windows.h>

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

O parâmetro Flags pode ser usado para personalizar o processamento da função GetNameInfoW . 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 pNodeBuffer .

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 posterior, 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 GetNameInfoW 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/rfc/rfc3493.txt

No Windows Server 2003 e versões 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 conhecido, a função GetNameInfoW 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 datagrama. Esse sinalizador é necessário para os poucos serviços que fornecem números de porta diferentes para o serviço UDP e TCP.

Nota A capacidade de executar pesquisas de DNS reverso usando a função GetNameInfoW é conveniente, mas essas pesquisas são consideradas inerentemente não confiáveis e devem ser usadas apenas como uma dica.

ObservaçãoGetNameInfoW não pode ser usado para resolve nomes de alias.

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.

Código de exemplo

O exemplo a seguir demonstra o uso da função GetNameInfoW .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#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;
    int iResult;

    DWORD dwRetval;

    struct sockaddr_in saGNI;
    WCHAR hostname[NI_MAXHOST];
    WCHAR servInfo[NI_MAXSERV];
    u_short port = 27015;

    // Validate the parameters
    if (argc != 2) {
        wprintf(L"usage: %s IPv4 address\n", argv[0]);
        wprintf(L"  to return hostname\n");
        wprintf(L"       %s 127.0.0.1\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;
    }
    //-----------------------------------------
    // 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 GetNameInfoW
    dwRetval = GetNameInfoW((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        wprintf(L"GetNameInfoW failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        wprintf(L"GetNameInfoW returned hostname = %ws\n", hostname);
        return 0;
    }
}

Observação

O cabeçalho ws2tcpip.h define GetNameInfo como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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