funzione getnameinfo (ws2tcpip.h)

Articolo
08/28/2023

La funzione getnameinfo fornisce la risoluzione dei nomi indipendenti dal protocollo da un indirizzo a un nome host ANSI e da un numero di porta al nome del servizio ANSI.

Sintassi

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

Parametri

[in] pSockaddr

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

[in] SockaddrLength

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

[out] pNodeBuffer

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

[in] NodeBufferSize

Lunghezza, in byte, del buffer a cui punta il parametro host . Il chiamante deve fornire un buffer sufficiente per contenere il nome host, incluso il carattere NULL terminante.

[out] pServiceBuffer

Puntatore a una stringa ANSI per contenere il nome del servizio. In caso di esito positivo, viene restituita una stringa ANSI che rappresenta il nome del servizio associato al numero di porta. Se il parametro serv è NULL, questo indica che il chiamante non vuole ricevere una stringa del nome del servizio.

[in] ServiceBufferSize

Lunghezza, in byte, del buffer a cui fa riferimento il parametro serv . Il chiamante deve fornire un buffer abbastanza grande per contenere il nome del servizio, incluso il carattere NULL terminante.

[in] Flags

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

Valore restituito

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

I codici di errore non zero restituiti dalla funzione getnameinfo vengono mappati anche al set di errori descritti dalle raccomandazioni di Internet Engineering Task Force (IETF). La tabella seguente elenca questi codici di errore e gli equivalenti WSA. È consigliabile usare i codici di errore WSA, poiché offrono informazioni di errore familiari e complete per i programmatori Winsock.

Valore di errore	WSA equivalente	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 getnameinfo . Questo errore viene restituito se è stato richiesto un nome host, ma il parametro hostlen era zero o se è stato richiesto un nome del servizio, ma il parametro servlen era zero.
EAI_FAIL	WSANO_RECOVERY	Si è verificato un errore non recuperabile nella risoluzione dei nomi.
EAI_FAMILY	WSAEAFNOSUPPORT	Il sa_family membro della struttura degli indirizzi socket a cui punta il parametro sa 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 del servizio, ma non è stato trovato alcun numero di porta nella struttura a cui punta il parametro sa o nessun nome di servizio corrispondente al numero di porta trovato. NI_NAMEREQD è impostato e il nome host non può trovarsi o sia i parametri host che serv erano NULL.

Usare la funzione gai_strerror per stampare messaggi di errore in base ai codici EAI restituiti dalla funzione getnameinfo . La funzione gai_strerror viene fornita per la conformità ai consigli di 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 sa è NULL o il parametro salen è minore della lunghezza necessaria per le dimensioni della struttura sockaddr_in per IPv4 o la struttura sockaddr_in6 per IPv6.

Commenti

La funzione getnameinfo è la versione ANSI di una funzione che fornisce la risoluzione dei nomi indipendenti dal protocollo. La funzione getnameinfo viene usata per tradurre il contenuto di una struttura di indirizzi socket in un nome del nodo e/o in un nome del servizio.

Per i protocolli IPv6 e IPv4, la risoluzione dei nomi può essere dal dns (Domain Name System), 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 getnameinfo può essere usata anche per convertire un indirizzo IP o un numero di porta in una struttura sockaddr in una stringa ANSI. Questa funzione può essere usata anche per determinare l'indirizzo IP per un nome host.

Un altro nome che può essere usato per la funzione getnameinfo è GetNameInfoA. Le macro nel file di intestazione Ws2tcpip.h definiscono GetNameInfoA per getnameinfo.

La versione Unicode di questa funzione disponibile in Windows XP con Service Pack 2 (SP2) e versioni successive è GetNameInfoW.

Le macro nel file di intestazione Winsock definiscono un nome di funzione mixed-case di GetNameInfo che può essere usato quando l'applicazione è destinata a Windows XP con SP2 e versioni successive (_WIN32_WINNT = 0x0502 >). Questa funzione GetNameInfo deve essere chiamata con i parametri host e serv di un puntatore di tipo TCHAR. Quando UNICODE o _UNICODE non è definito, GetNameInfo viene definito nella versione ANSI e getnameinfo viene chiamato con i parametri host e serv di un puntatore di tipo char. Quando viene definito UNICODE o _UNICODE, GetNameInfo viene definito nella versione Unicode e GetNameInfoW 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 host e serv, i valori seguenti per la lunghezza massima del nome host e il nome massimo del servizio sono definiti nel file di intestazione Ws2tcpip.h.

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Il parametro flag può essere usato per personalizzare l'elaborazione della funzione getnameinfo . 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 da DNS genera un errore.

Se si imposta il flag di NI_NOFQDN , gli host locali hanno solo il nome distinto relativo (RDN) restituito nel parametro host .

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

L'impostazione del flag di NI_NUMERICSERV restituisce il numero di porta del servizio anziché il relativo nome. Inoltre, se un nome host non viene trovato 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 flag e il numero di porta contenuto nella struttura sockaddr a cui punta il parametro sa non viene risolto in un servizio noto, la funzione getnameinfo restituisce la forma numerica dell'indirizzo del servizio (il numero di porta) come stringa numerica. Quando viene specificato 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/rfc3493.txt

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

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

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

Nota Impossibile usare la funzione getnameinfo per risolvere i nomi alias.

Codice di esempio

Nell'esempio di codice seguente viene illustrato come usare la funzione 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;
    }
}

Supporto per getnameinfo nelle versioni precedenti di Windows

La funzione getnameinfo è stata aggiunta alla Ws2_32.dll in Windows XP e versioni successive. Se si vuole eseguire un'applicazione usando questa funzione nelle versioni precedenti di Windows (Windows 2000, Windows NT e Windows Me/98/95), è necessario includere il file Ws2tcpip.h e includere anche il file Wspiapi.h . Quando viene aggiunto il file di inclusione Wspiapi.h , la funzione getnameinfo viene definita nella funzione inline WspiapiGetNameInfo nel file Wspiapi.h . In fase di esecuzione, la funzione WspiapiGetNameInfo viene implementata in modo tale che se il Ws2_32.dll o il Wship6.dll (il file contenente getnameinfo nell'anteprima della tecnologia IPv6 per Windows 2000) non include getnameinfo, quindi una versione di getnameinfo viene implementata inline in base al codice nel file di intestazione Wspiapi.h. Questo codice inline verrà usato nelle piattaforme Windows meno recenti che non supportano in modo nativo la funzione getnameinfo .

Il protocollo IPv6 è supportato in Windows 2000 quando viene installata l'anteprima della tecnologia IPv6 per Windows 2000. In caso contrario , il supporto getnameinfo nelle versioni di Windows precedenti a Windows XP è limitato alla gestione della risoluzione dei nomi IPv4.

La funzione GetNameInfoW è la versione Unicode di getnameinfo. La funzione GetNameInfoW è stata aggiunta alla Ws2_32.dll in Windows XP con SP2. La funzione GetNameInfoW non può essere usata nelle versioni di Windows precedenti a Windows XP con SP2.

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store 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.

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