Funzione GetNameInfoW (ws2tcpip.h)

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.

È 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.

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.

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

#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;
    }
}

Requisiti

Vedi anche

GetAddrInfoW

WSAGetLastError

Funzioni Winsock

Informazioni di riferimento su Winsock

gai_strerror

getaddrinfo

getnameinfo

sockaddr