Funzione GetAddrInfoW (ws2tcpip.h)
La funzione GetAddrInfoW
Sintassi
INT WSAAPI GetAddrInfoW(
[in, optional] PCWSTR pNodeName,
[in, optional] PCWSTR pServiceName,
[in, optional] const ADDRINFOW *pHints,
[out] PADDRINFOW *ppResult
);
Parametri
[in, optional] pNodeName
Puntatore a un NULLstringa Unicode con terminazione che contiene un nome host (nodo) o una stringa di indirizzo host numerico. Per il protocollo Internet, la stringa di indirizzo host numerico è un indirizzo IPv4 decimale punteggiato o un indirizzo esadecimale IPv6.
[in, optional] pServiceName
Puntatore a un NULLstringa Unicode con terminazione che contiene un nome del servizio o un numero di porta rappresentato come stringa.
Un nome del servizio è un alias stringa per un numero di porta. Ad esempio, "http" è un alias per la porta 80 definita da Internet Engineering Task Force (IETF) come porta predefinita usata dai server Web per il protocollo HTTP. I valori possibili per il parametro pServiceName quando non è specificato un numero di porta sono elencati nel file seguente:
%WINDIR%\system32\drivers\etc\services
[in, optional] pHints
Puntatore a una struttura addrinfoW che fornisce suggerimenti sul tipo di socket supportato dal chiamante.
I membri
Per altri dettagli, vedere la sezione Osservazioni.
[out] ppResult
Puntatore a un elenco collegato di una o più strutture addrinfoW che contengono informazioni di risposta sull'host.
Valore restituito
L'operazione riuscita restituisce zero. L'errore restituisce un codice di errore windows Sockets diverso da zero, come indicato nella codici di errore di Windows Sockets.
La maggior parte dei codici di errore diversi da zero restituiti dalla funzione GetAddrInfoW mappa al set di errori descritti dalle raccomandazioni IETF (Internet Engineering Task Force). Nella tabella seguente sono elencati questi codici di errore e i relativi equivalenti WSA. È consigliabile usare i codici di errore WSA, perché offrono informazioni di errore 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 | Per il membro |
| EAI_FAIL | WSANO_RECOVERY | Si è verificato un errore irreversibile nella risoluzione dei nomi. |
| EAI_FAMILY | WSAEAFNOSUPPORT | Il membro |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Si è verificato un errore di allocazione della memoria. |
| EAI_NONAME | WSAHOST_NOT_FOUND | Il nome non viene risolto per i parametri forniti o per i parametri pNodeName e non sono stati forniti parametri pServiceName. |
| EAI_SERVICE | WSATYPE_NOT_FOUND | Il parametro pServiceName |
| EAI_SOCKTYPE | WSAESOCKTNOSUPPORT | Il membro |
Utilizzare la funzione gai_strerror per stampare i messaggi di errore in base ai codici EAI_* restituiti dalla funzione GetAddrInfoW. La funzione gai_strerror viene fornita per la conformità con le raccomandazioni IETF, ma non è thread-safe. Pertanto, è consigliabile usare una funzione Windows Sockets tradizionale, ad esempio WSAGetLastError.
| Codice di errore | Significato |
|---|---|
| Memoria insufficiente per eseguire l'operazione. | |
|
È stato usato un indirizzo incompatibile con il protocollo richiesto. Questo errore viene restituito se il membro |
|
|
È stato fornito un argomento non valido. Questo errore viene restituito se è stato specificato un valore non valido per il membro |
|
|
Il supporto per il tipo di socket specificato non esiste in questa famiglia di indirizzi. Questo errore viene restituito se il membro |
|
Nessun host di questo tipo è noto. Questo errore viene restituito se il nome non viene risolto per i parametri specificati o se non sono stati specificati i parametri pNodename |
|
| Il nome richiesto è valido, ma non sono stati trovati dati del tipo richiesto. | |
| Si è verificato un errore irreversibile durante una ricerca del database. Questo errore viene restituito se si è verificato un errore irreversibile nella risoluzione dei nomi. | |
| Prima di usare questa funzione, è necessario eseguire una WSAStartup chiamata. | |
| Si tratta in genere di un errore temporaneo durante la risoluzione del nome host e indica che il server locale non ha ricevuto una risposta da un server autorevole. Questo errore viene restituito quando si è verificato un errore temporaneo nella risoluzione dei nomi. | |
|
Impossibile trovare la classe specificata. Il parametro pServiceName |
Osservazioni
La funzione GetAddrInfoW
La funzione getAddrInfoW
Le macro nel file di intestazione Winsock definiscono un nome di funzione con maiuscole e minuscole GetAddrInfo e una struttura ADDRINFOT. Questa
Uno o entrambi i parametri pNodeName o pServiceName devono puntare a una stringa Unicode NULLcon terminazione; in genere vengono forniti entrambi.
In caso di esito positivo, viene restituito un elenco collegato di strutture addrinfoW nel parametro ppResult. L'elenco può essere elaborato seguendo il puntatore fornito nel membro
Se il parametro pNodeName punta a un nome computer, vengono restituiti tutti gli indirizzi permanenti per il computer che può essere utilizzato come indirizzo di origine. In Windows Vista e versioni successive, questi indirizzi includono tutti gli indirizzi IP unicast restituiti dal GetUnicastIpAddressTable o GetUnicastIpAddressEntry funzioni in cui il membro SkipAsSource è impostato su false nella struttura MIB_UNICASTIPADDRESS_ROW.
Se il parametro pNodeName punta a una stringa uguale a "localhost", vengono restituiti tutti gli indirizzi di loopback nel computer locale.
Se il parametro pNodeName contiene una stringa vuota, vengono restituiti tutti gli indirizzi registrati nel computer locale.
In Windows Server 2003 e versioni successive se il parametro pNodeName punta a una stringa uguale a ".. localmachine", vengono restituiti tutti gli indirizzi registrati nel computer locale.
Se il parametro pNodeName fa riferimento a un nome del server virtuale del cluster, vengono restituiti solo gli indirizzi del server virtuale. In Windows Vista e versioni successive, questi indirizzi includono tutti gli indirizzi IP unicast restituiti dal
Windows 7 con Service Pack 1 (SP1) e Windows Server 2008 R2 con Service Pack 1 (SP1) aggiungono supporto a Netsh.exe per impostare l'attributo SkipAsSource su un indirizzo IP. Questo cambia anche il comportamento in modo che, se il SkipAsSource membro nella struttura MIB_UNICASTIPADDRESS_ROW è impostato su false, l'indirizzo IP verrà registrato in DNS. Se il membro SkipAsSource è impostato su true, l'indirizzo IP non viene registrato in DNS.
Un hotfix è disponibile per Windows 7 e Windows Server 2008 R2 che aggiunge il supporto a Netsh.exe per impostare l'attributo SkipAsSource su un indirizzo IP. Questo hotfix modifica anche il comportamento in modo che, se il membro SkipAsSource
È disponibile anche un hotfix simile per Windows Vista con Service Pack 2 (SP2) e Windows Server 2008 con Service Pack 2 (SP2) che aggiunge supporto a Netsh.exe per l'impostazione dell'attributo SkipAsSource in un indirizzo IP. Questo hotfix modifica anche il comportamento in modo che, se il membro SkipAsSource
I chiamanti della funzione
- Il valore AF_UNSPEC per ai_family indica che il chiamante accetterà solo le famiglie di indirizzi AF_INET e AF_INET6. Si noti che AF_UNSPEC e PF_UNSPEC sono uguali.
- Un valore pari a zero per ai_socktype indica che il chiamante accetterà qualsiasi tipo di socket.
- Il valore zero per ai_protocol indica che il chiamante accetterà qualsiasi protocollo.
- Il membro ai_addrlen deve essere impostato su zero.
- Il membro ai_canonname deve essere impostato su NULL.
- Il membro ai_addr deve essere impostato su NULL.
- Il membro ai_next deve essere impostato su NULL.
Altri valori nella struttura addrinfoW
Se il parametro
In Windows Vista e versioni successive, quando getAddrInfoW viene chiamato da un servizio, se l'operazione è il risultato di un processo utente che chiama il servizio, il servizio deve rappresentare l'utente. Ciò consente di applicare correttamente la sicurezza.
La funzione getAddrInfoW
liberare informazioni sugli indirizzi dall'allocazione dinamica
Tutte le informazioni restituite dalla funzione GetAddrInfoWcodice di esempio
Nell'esempio di codice seguente viene illustrato come usare la funzione#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")
// set APPVER=5.02 for WinXP SP2 and later
int __cdecl wmain(int argc, wchar_t **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
INT iRetval;
DWORD dwRetval;
int i = 1;
ADDRINFOW *result = NULL;
ADDRINFOW *ptr = NULL;
ADDRINFOW hints;
// struct sockaddr_in6 *sockaddr_ipv6;
LPSOCKADDR sockaddr_ip;
wchar_t ipstringbuffer[46];
DWORD ipbufferlength = 46;
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
wprintf(L"getaddrinfow provides protocol-independent translation\n");
wprintf(L" from an Unicode host name to an IP address\n");
wprintf(L"%ws example usage\n", argv[0]);
wprintf(L" %ws www.contoso.com 0\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;
}
//--------------------------------
// Setup the hints address info structure
// which is passed to the getaddrinfo() function
ZeroMemory( &hints, sizeof(hints) );
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
wprintf(L"Calling getaddrinfow with following parameters:\n");
wprintf(L"\tnodename = %ws\n", argv[1]);
wprintf(L"\tservname (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrinfoW(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfow structures containing response
// information
dwRetval = GetAddrInfoW(argv[1], argv[2], &hints, &result);
if ( dwRetval != 0 ) {
wprintf(L"GetAddrInfoW failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
wprintf(L"GetAddrInfoW returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
wprintf(L"GetAddrInfoW response %d\n", i++);
wprintf(L"\tFlags: 0x%x\n", ptr->ai_flags);
wprintf(L"\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
wprintf(L"Unspecified\n");
break;
case AF_INET:
wprintf(L"AF_INET (IPv4)\n");
sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
// The buffer length is changed by each call to WSAAddresstoString
// So we need to set it for each iteration through the loop for safety
ipbufferlength = 46;
iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL,
ipstringbuffer, &ipbufferlength );
if (iRetval)
wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
else
wprintf(L"\tIPv4 address %ws\n", ipstringbuffer);
break;
case AF_INET6:
wprintf(L"AF_INET6 (IPv6)\n");
// the InetNtop function is available on Windows Vista and later
// sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
// printf("\tIPv6 address %s\n",
// InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstringbuffer, 46) );
// We use WSAAddressToString since it is supported on Windows XP and later
sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
// The buffer length is changed by each call to WSAAddresstoString
// So we need to set it for each iteration through the loop for safety
ipbufferlength = 46;
iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL,
ipstringbuffer, &ipbufferlength );
if (iRetval)
wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
else
wprintf(L"\tIPv6 address %ws\n", ipstringbuffer);
break;
default:
wprintf(L"Other %ld\n", ptr->ai_family);
break;
}
wprintf(L"\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
wprintf(L"Unspecified\n");
break;
case SOCK_STREAM:
wprintf(L"SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
wprintf(L"SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
wprintf(L"SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
wprintf(L"SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
wprintf(L"SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_socktype);
break;
}
wprintf(L"\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
wprintf(L"Unspecified\n");
break;
case IPPROTO_TCP:
wprintf(L"IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
wprintf(L"IPPROTO_UDP (UDP) \n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_protocol);
break;
}
wprintf(L"\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
wprintf(L"\tCanonical name: %s\n", ptr->ai_canonname);
}
FreeAddrInfoW(result);
WSACleanup();
return 0;
}
nomi di dominio internazionalizzati
I nomi host Internet in genere sono costituiti da un set di caratteri molto limitato:- Lettere ASCII maiuscole e minuscole dell'alfabeto inglese.
- Cifre da 0 a 9.
- Caratteri trattini ASCII.
Con la crescita di Internet, c'è una crescente necessità di identificare i nomi host Internet per altre lingue non rappresentate dal set di caratteri ASCII. Gli identificatori che facilitano questa esigenza e consentono la rappresentazione di caratteri non ASCII (Unicode) come stringhe di caratteri ASCII speciali sono noti come nomi di dominio internazionalizzati (IDN). Un meccanismo denominato Internationalizing Domain Names in Applications (IDNA) viene usato per gestire gli IDN in modo standard. Le specifiche per IDN e IDNA sono documentate in RFC 3490, RTF 5890e RFC 6365 pubblicato da Internet Engineering Task Force (IETF).
In Windows 8 e Windows Server 2012, la funzione GetAddrInfoW
In Windows 7 e Windows Server 2008 R2 o versioni precedenti, la funzione GetAddrInfoW non fornisce attualmente il supporto per l'analisi IDN applicata al nome passato nel parametro pNodeName. Winsock non esegue alcuna conversione Punycode/IDN. La funzione GetAddrInfoW
Diverse funzioni in Windows Vista e versioni successive supportano la conversione tra etichette Unicode in un IDN ai relativi equivalenti ASCII. La rappresentazione risultante di ogni etichetta Unicode contiene solo caratteri ASCII e inizia con il prefisso xn-- se l'etichetta Unicode contiene caratteri non ASCII. Il motivo è supportare i server DNS esistenti su Internet, poiché alcuni strumenti e server DNS supportano solo caratteri ASCII (vedere RFC 3490).
La funzione IdnToAscii usa Punycode per convertire un IDN nella rappresentazione ASCII della stringa Unicode originale usando l'algoritmo standard definito in RFC 3490. La funzione IdnToUnicode
La funzione IdnToAscii può essere usata per convertire un nome IDN nel formato ASCII. Per passare questo modulo ASCII alla funzione di GetAddrInfoW
Uso di ai_flags nel parametro hints
Flag nel membro ai_flags della struttura addrinfoW facoltativa fornita nella parametro modificare il comportamento della funzione.
Questi bit di flag sono definiti nel file di intestazione Ws2def.h nel Microsoft Windows Software Development Kit (SDK) per Windows 7. Questi bit di flag sono definiti nel file di intestazione Ws2tcpip.h in Windows SDK per Windows Server 2008 e Windows Vista. Questi bit di flag sono definiti nel file di intestazione Ws2tcpip.h nel file di intestazione Platform Software Development Kit (SDK) per Windows Server 2003 e Windows XP.
I bit di flag possono essere una combinazione dei seguenti elementi:
| Flag Bits | Descrizione |
|---|---|
| AI_PASSIVE |
L'impostazione del flag Quando il flag di AI_PASSIVE non è impostato, la struttura di indirizzi socket restituita è pronta per una chiamata alla funzione connect per un protocollo orientato alla connessione oppure pronta per una chiamata al connettersi, sendtoo inviare funzioni di per un protocollo senza connessione. Se il parametro pNodeName è un puntatore NULL in questo caso, la parte dell'indirizzo IP della struttura di indirizzi socket viene impostata sull'indirizzo loopback. |
| AI_CANONNAME |
Se non vengono usati né Quando il bit AI_CANONNAME è impostato, il parametro pNodeName non può essere NULL. In caso contrario, la funzione GetAddrInfoEx avrà esito negativo con WSANO_RECOVERY. Quando il bit AI_CANONNAME viene impostato e la funzione GetAddrInfoW restituisce esito positivo, il membro ai_canonname nel parametro ppResult punta a una stringa NULL-terminate contenente il nome canonico del nodo specificato. |
| AI_NUMERICHOST | Quando il bit AI_NUMERICHOST è impostato, il parametro pNodeName deve contenere un valore nullnull stringa di indirizzo host numerico; in caso contrario, viene restituito l'errore EAI_NONAME. Questo flag impedisce la chiamata di un servizio di risoluzione dei nomi. |
| AI_NUMERICSERV |
Quando il bit di Il flag AI_NUMERICSERV è definito in Windows SDK per Windows Vista e versioni successive. Il flag AI_NUMERICSERV non è supportato dai provider Microsoft. |
| AI_ALL |
Se il bit AI_ALL è impostato, viene effettuata una richiesta per gli indirizzi IPv6 e gli indirizzi IPv4 con AI_V4MAPPED.
Il flag AI_ALL è definito in Windows SDK per Windows Vista e versioni successive. Il flag AI_ALL è supportato in Windows Vista e versioni successive. |
| AI_ADDRCONFIG |
Se il bit AI_ADDRCONFIG è impostato, GetAddrInfoW verrà risolto solo se è configurato un indirizzo globale. Se si specifica AI_ADDRCONFIG flag, gli indirizzi IPv4 verranno restituiti solo se nel sistema locale è configurato un indirizzo IPv4 e gli indirizzi IPv6 verranno restituiti solo se nel sistema locale è configurato un indirizzo IPv6. L'indirizzo di loopback IPv4 o IPv6 non è considerato un indirizzo globale valido.
Il flag AI_ADDRCONFIG è definito in Windows SDK per Windows Vista e versioni successive. Il flag AI_ADDRCONFIG è supportato in Windows Vista e versioni successive. |
| AI_V4MAPPED |
Se il bit di AI_V4MAPPED è impostato e una richiesta per gli indirizzi IPv6 ha esito negativo, viene effettuata una richiesta di servizio dei nomi per gli indirizzi IPv4 e questi indirizzi vengono convertiti in formato indirizzo IPv4 mappato a IPv6.
Il flag AI_V4MAPPED è definito in Windows SDK per Windows Vista e versioni successive. Il flag AI_V4MAPPED è supportato in Windows Vista e versioni successive. |
| AI_NON_AUTHORITATIVE |
Se il bit AI_NON_AUTHORITATIVE è impostato, il provider dello spazio dei nomi NS_EMAIL restituisce risultati autorevoli e non autorevoli. Se il bit AI_NON_AUTHORITATIVE non è impostato, il provider dello spazio dei nomi NS_EMAIL restituisce solo risultati autorevoli.
Il flag AI_NON_AUTHORITATIVE viene definito in Windows SDK per Windows Vista e versioni successive. Il flag AI_NON_AUTHORITATIVE è supportato in Windows Vista e versioni successive e si applica solo allo spazio dei nomi NS_EMAIL. |
| AI_SECURE |
Se il bit AI_SECURE è impostato, il provider dello spazio dei nomi NS_EMAIL restituirà i risultati ottenuti con sicurezza avanzata per ridurre al minimo i possibili spoofing.
Il flag AI_SECURE è definito in Windows SDK per Windows Vista e versioni successive. Il flag AI_SECURE è supportato in Windows Vista e versioni successive e si applica solo allo spazio dei nomi NS_EMAIL. |
| AI_RETURN_PREFERRED_NAMES |
Se la Il flag AI_RETURN_PREFERRED_NAMES è definito in Windows SDK per Windows Vista e versioni successive. Il flag AI_RETURN_PREFERRED_NAMES è supportato in Windows Vista e versioni successive e si applica solo allo spazio dei nomi NS_EMAIL. |
| AI_FQDN |
Se il AI_FQDN è impostato e viene specificato un nome flat (etichetta singola), GetAddrInfoW restituirà il nome di dominio completo in cui il nome verrà risolto. Il nome di dominio completo viene restituito nel membro Quando il bit di Windows 7: Il flag AI_FQDN è definito in Windows SDK per Windows 7 e versioni successive. Il flag AI_FQDN è supportato in Windows 7 e versioni successive. |
| AI_FILESERVER |
Se la AI_FILESERVER è impostata, si tratta di un suggerimento per il provider dello spazio dei nomi su cui viene eseguita la query sul nome host nello scenario di condivisione file. Il provider dello spazio dei nomi può ignorare questo hint.
Windows 7: Il flag AI_FILESERVER è definito in Windows SDK per Windows 7 e versioni successive. Il flag AI_FILESERVER è supportato in Windows 7 e versioni successive. |
| AI_DISABLE_IDN_ENCODING |
Se la AI_DISABLE_IDN_ENCODING è impostata, questa opzione disabilita la codifica automatica del nome di dominio internazionale usando Punycode nelle funzioni di risoluzione dei nomi chiamate dalla funzione di GetAddrInfoW.
Windows 8: Il flag AI_DISABLE_IDN_ENCODING è definito in Windows SDK per Windows 8 e versioni successive. Il flag AI_DISABLE_IDN_ENCODING è supportato in Windows 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.
Nota
L'intestazione ws2tcpip.h definisce GetAddrInfo 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 XP, Windows 8.1 [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 |