Funzione GetNameInfoW (ws2tcpip.h)

Articolo
03/13/2024

La funzione GetNameInfoW fornisce la risoluzione dei nomi indipendente dal protocollo da un indirizzo a un nome host Unicode e da un numero di porta al nome del servizio Unicode.

Sintassi

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
);

Parametri

[in] pSockaddr

Puntatore a una struttura di indirizzi socket contenente l'indirizzo IP e il numero di porta del socket. Per IPv4, il parametro pSockaddr punta a una struttura sockaddr_in . Per IPv6, il parametro pSockaddr punta a una struttura sockaddr_in6 .

[in] SockaddrLength

Lunghezza, in byte, della struttura a cui punta il parametro pSockaddr .

[out] pNodeBuffer

Puntatore a una stringa Unicode per contenere il nome host. In caso di esito positivo, un puntatore al nome host Unicode viene restituito come nome di dominio completo (FQDN) per impostazione predefinita. Se il parametro pNodeBuffer è NULL, indica che il chiamante non vuole ricevere una stringa del nome host.

[in] NodeBufferSize

Numero di caratteri WCHAR nel buffer a cui punta il parametro pNodeBuffer . Il chiamante deve fornire un buffer sufficientemente grande da contenere il nome host Unicode, incluso il carattere NULL di terminazione.

[out] pServiceBuffer

Puntatore a una stringa Unicode che contiene il nome del servizio. In caso di esito positivo, un puntatore viene restituito a una stringa Unicode che rappresenta il nome del servizio associato al numero di porta. Se il parametro pServiceBuffer è NULL, indica che il chiamante non vuole ricevere una stringa del nome del servizio.

[in] ServiceBufferSize

Numero di caratteri WCHAR nel buffer a cui punta il parametro pServiceBuffer . Il chiamante deve fornire un buffer sufficientemente grande da contenere il nome del servizio Unicode, incluso il carattere NULL di terminazione.

[in] Flags

Valore utilizzato per personalizzare l'elaborazione della funzione GetNameInfoW . Vedere la sezione relativa alle osservazioni.

Valore restituito

In caso di esito positivo, GetNameInfoW restituisce zero. Qualsiasi valore restituito diverso da zero indica un errore e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

I codici di errore diversi da zero restituiti dalla funzione GetNameInfoW eseguono anche il mapping al set di errori descritti dalle raccomandazioni di Internet Engineering Task Force (IETF). La tabella seguente illustra questi codici di errore e i relativi equivalenti WSA. È consigliabile usare i codici di errore WSA, in quanto offrono informazioni sugli errori familiari e complete per i programmatori Winsock.

Valore di errore	Equivalente WSA	Descrizione
EAI_AGAIN	WSATRY_AGAIN	Si è verificato un errore temporaneo nella risoluzione dei nomi.
EAI_BADFLAGS	WSAEINVAL	Uno o più parametri non validi sono stati passati alla funzione GetNameInfoW . Questo errore viene restituito se è stato richiesto un nome host, ma il parametro NodeBufferSize era zero o se è stato richiesto un nome di servizio ma il parametro ServiceBufferSize era zero.
EAI_FAIL	WSANO_RECOVERY	Si è verificato un errore irreversibile nella risoluzione dei nomi.
EAI_FAMILY	WSAEAFNOSUPPORT	Il sa_family membro della struttura di indirizzi socket a cui punta il parametro pSockaddr non è supportato.
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	Si è verificato un errore di allocazione della memoria.
EAI_NONAME	WSAHOST_NOT_FOUND	È stato richiesto un nome di servizio, ma non è stato trovato alcun numero di porta nella struttura a cui punta il parametro pSockaddr o nessun nome del servizio corrispondente al numero di porta trovato. NI_NAMEREQD è impostato e non è possibile individuare il nome dell'host oppure i parametri pNodeBuffer e pServiceBuffer sono NULL.

È possibile usare la funzione gai_strerror per stampare i messaggi di errore in base ai codici EAI restituiti dalla funzione GetNameInfoW . La funzione gai_strerror viene fornita per la conformità con le raccomandazioni IETF, ma non è thread-safe. Pertanto, è consigliabile usare le funzioni tradizionali di Windows Sockets, ad esempio WSAGetLastError .

Inoltre, è possibile restituire i codici di errore seguenti.

Codice di errore	Significato
WSAEFAULT	Questo errore viene restituito se il parametro pSockaddr è NULL o il parametro SockaddrLength è minore della lunghezza necessaria per le dimensioni della struttura sockaddr_in per IPv4 o la struttura sockaddr_in6 per IPv6.

Commenti

La funzione GetNameInfoW è la versione Unicode di una funzione che fornisce la risoluzione dei nomi indipendente dal protocollo. La funzione GetNameInfoW viene utilizzata per convertire il contenuto di una struttura di indirizzi socket in un nome di nodo e/o in un nome di servizio.

Per i protocolli IPv6 e IPv4, la risoluzione dei nomi può essere eseguita da Domain Name System (DNS), da un file host locale o da altri meccanismi di denominazione. Questa funzione può essere usata per determinare il nome host per un indirizzo IPv4 o IPv6, una ricerca DNS inversa o determinare il nome del servizio per un numero di porta. La funzione GetNameInfoW può essere usata anche per convertire un indirizzo IP o un numero di porta in una struttura SOCKADDR in una stringa Unicode. Questa funzione può essere usata anche per determinare l'indirizzo IP per un nome host.

La versione ANSI di questa funzione è getnameinfo.

Le macro nel file di intestazione Winsock definiscono un nome di funzione con maiuscole e minuscole getNameInfo che può essere usato quando l'applicazione è destinata a Windows XP con Service Pack 2 (SP2) e versioni successive (_WIN32_WINNT = 0x0502 >). Questa funzione GetNameInfo deve essere chiamata con i parametri pNodeBuffer e pServiceBuffer di un puntatore di tipo TCHAR. Quando viene definito UNICODE o _UNICODE, GetNameInfo viene definito per la versione Unicode e GetNameInfoW viene chiamato con i parametri host e serv di un puntatore di tipo char. Quando UNICODE o _UNICODE non è definito, GetNameInfo viene definito nella versione ANSI e getnameinfo viene chiamato con i parametri pNodeBuffer e pServiceBuffer di un puntatore di tipo PWCHAR.

Per semplificare la determinazione dei requisiti del buffer per i parametri pNodeBuffer e pServiceBuffer , i valori seguenti per la lunghezza massima del nome host e il nome massimo del servizio sono definiti nel file di intestazione Ws2tcpip.h :

#include <windows.h>

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Il parametro Flags può essere usato per personalizzare l'elaborazione della funzione GetNameInfoW . Sono disponibili i flag seguenti:

NI_NOFQDN
NI_NUMERICHOST
NI_NAMEREQD
NI_NUMERICSERV
NI_DGRAM

Quando il flag NI_NAMEREQD è impostato, un nome host che non può essere risolto dal DNS genera un errore.

L'impostazione del flag NI_NOFQDN comporta che gli host locali presentino solo il relativo nome distinto (RDN) restituito nel parametro pNodeBuffer .

L'impostazione del flag NI_NUMERICHOST restituisce la forma numerica del nome host anziché il nome. La forma numerica del nome host viene restituita anche se il nome host non può essere risolto da DNS.

L'impostazione del flag NI_NUMERICSERV restituisce il numero di porta del servizio anziché il relativo nome. Inoltre, se non viene trovato un nome host per un indirizzo IP (127.0.0.2, ad esempio), il nome host viene restituito come indirizzo IP.

In Windows Vista e versioni successive, se NI_NUMERICSERV non viene specificato nel parametro flags e il numero di porta contenuto nella struttura sockaddr a cui punta il parametro sa non viene risolto in un servizio noto, la funzione GetNameInfoW restituisce la forma numerica dell'indirizzo del servizio (il numero di porta) come stringa numerica. Quando si specifica NI_NUMERICSERV , il numero di porta viene restituito come stringa numerica. Questo comportamento viene specificato nella sezione 6.2 di RFC 3493. Per altre informazioni, vedere www.ietf.org/rfc/rfc3493.txt

In Windows Server 2003 e versioni precedenti, se NI_NUMERICSERV non è specificato nel parametro flags e il numero di porta contenuto nella struttura sockaddr a cui punta il parametro sa non si risolve in un servizio noto, la funzione GetNameInfoW ha esito negativo. Quando si specifica NI_NUMERICSERV , il numero di porta viene restituito come stringa numerica.

L'impostazione del flag NI_DGRAM indica che il servizio è un servizio datagrammi. Questo flag è necessario per i pochi servizi che forniscono numeri di porta diversi per il servizio UDP e TCP.

Nota La possibilità di eseguire ricerche DNS inverse usando la funzione GetNameInfoW è utile, ma tali ricerche sono considerate intrinsecamente inaffidabili e devono essere usate solo come hint.

NotaGetNameInfoW non può essere usato per risolvere i nomi degli alias.

Windows Phone 8: questa funzione è supportata per le app dello Store di Windows Phone in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Codice di esempio

Nell'esempio seguente viene illustrato l'uso della funzione 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;
    }
}

Nota

L'intestazione ws2tcpip.h definisce GetNameInfo come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	ws2tcpip.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll