Funzione GetNameInfoW (ws2tcpip.h)
La funzione GetNameInfoW
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
[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
[in] NodeBufferSize
Numero di caratteri
[out] pServiceBuffer
Puntatore a una stringa Unicode per contenere il nome del servizio. In caso di esito positivo, viene restituito un puntatore 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
[in] Flags
Valore utilizzato per personalizzare l'elaborazione della funzione GetNameInfoW
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
| 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 |
| EAI_FAIL | WSANO_RECOVERY | Si è verificato un errore irreversibile nella risoluzione dei nomi. |
| EAI_FAMILY | WSAEAFNOSUPPORT | Il |
| 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 di servizio corrispondente al numero di porta trovato. NI_NAMEREQD è impostato e non è possibile trovare il nome dell'host oppure entrambi i parametri pNodeBuffer e pServiceBuffer erano NULL. |
È possibile utilizzare la funzione
È inoltre possibile restituire i codici di errore seguenti.
| Codice di errore | Significato |
|---|---|
|
Questo errore viene restituito se il parametro |
Osservazioni
La funzione GetNameInfoW è la versione Unicode di una funzione che fornisce la risoluzione dei nomi indipendente dal protocollo. La funzione GetNameInfoW viene usata 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 dal dns (Domain Name System), da un locale host file 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
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 possono essere usate quando l'applicazione è destinata a Windows XP con Service Pack 2 (SP2) e versioni successive (_WIN32_WINNT >= 0x0502). Questa funzione
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 vengono definiti nel file di intestazione Ws2tcpip. h:
#include <windows.h>
#define NI_MAXSERV 32
#define NI_MAXHOST 1025
Il parametro
- 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.
Se si imposta il flag NI_NOFQDN, gli host locali hanno restituito solo il relativo nome distinto (RDN) 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
In Windows Server 2003 e versioni precedenti, se
L'impostazione del flag NI_DGRAM indica che il servizio è un servizio di 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 di 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.
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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| 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 | Finestre |
| intestazione |
ws2tcpip.h |
| libreria |
Ws2_32.lib |
| dll | Ws2_32.dll |