Funzione GetAddrInfoW (ws2tcpip.h)

Articolo
08/28/2023

La funzione GetAddrInfoW fornisce una traduzione indipendente dal protocollo da un nome host Unicode a un indirizzo.

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 una stringa Unicode con terminazione NULL contenente un nome host (nodo) o una stringa di indirizzo host numerico. Per il protocollo Internet, la stringa di indirizzo host numerico è un indirizzo IPv4 con estensione decimale o un indirizzo esadecimale IPv6.

[in, optional] pServiceName

Puntatore a una stringa Unicode con terminazione NULL contenente 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 dalla Internet Engineering Task Force (IETF) come porta predefinita utilizzata dai server Web per il protocollo HTTP. I valori possibili per il parametro pServiceName quando non viene 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 hint sul tipo di socket supportato dal chiamante.

I membri ai_addrlen, ai_canonname, ai_addr e ai_next della struttura addrinfoW a cui punta il parametro pHints devono essere zero o NULL. In caso contrario, la funzione GetAddrInfoEx avrà esito negativo con WSANO_RECOVERY.

Per altri dettagli, vedere le osservazioni.

[out] ppResult

Puntatore a un elenco collegato di una o più strutture addrinfoW che contengono informazioni sulla risposta sull'host.

Valore restituito

Il successo restituisce zero. L'errore restituisce un codice di errore Windows Sockets diverso da zero, come indicato nei codici di errore di Windows Sockets.

La maggior parte dei codici di errore non zero restituiti dalla funzione GetAddrInfoW viene mappata 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	È stato fornito un valore non valido per il membro ai_flags del parametro pHints .
EAI_FAIL	WSANO_RECOVERY	Si è verificato un errore non recuperabile nella risoluzione dei nomi.
EAI_FAMILY	WSAEAFNOSUPPORT	Il ai_family membro del parametro pHints non è supportato.
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 specificati o i parametri pNodeName e pServiceName non sono stati specificati.
EAI_SERVICE	WSATYPE_NOT_FOUND	Il parametro pServiceName non è supportato per il membro ai_socktype specificato del parametro pHints .
EAI_SOCKTYPE	WSAESOCKTNOSUPPORT	Il ai_socktype membro del parametro pHints non è supportato.

Usare la funzione gai_strerror per stampare messaggi di errore in base ai codici EAI_* restituiti dalla funzione GetAddrInfoW . La funzione gai_strerror viene fornita per la conformità ai consigli di IETF, ma non è thread safe. Pertanto, è consigliabile usare una funzione Windows Sockets tradizionale, ad esempio WSAGetLastError.

Codice di errore	Significato
WSA_NOT_ENOUGH_MEMORY	Memoria insufficiente per eseguire l'operazione.
WSAEAFNOSUPPORT	È stato usato un indirizzo incompatibile con il protocollo richiesto. Questo errore viene restituito se il membro ai_family della struttura addrinfoW puntato al parametro hints non è supportato.
WSAEINVAL	Argomento fornito non valido. Questo errore viene restituito se viene fornito un valore non valido per il membro ai_flags della struttura addrinfoW a cui punta il parametro hint .
WSAESOCKTNOSUPPORT	Il supporto per il tipo di socket specificato non esiste in questa famiglia di indirizzi. Questo errore viene restituito se il ai_socktype membro della struttura addrinfoW puntato al parametro hints non è supportato.
WSAHOST_NOT_FOUND	L'host è sconosciuto. Questo errore viene restituito se il nome non viene risolto per i parametri specificati o i parametri pNodename e pServicename non sono stati specificati.
WSANO_DATA	Il nome richiesto è valido, ma non sono stati trovati dati del tipo richiesto.
WSANO_RECOVERY	Si è verificato un errore irreversibile durante una ricerca nel database. Questo errore viene restituito se si è verificato un errore non recuperabile nella risoluzione dei nomi.
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.
WSATRY_AGAIN	Generalmente, questo è un errore temporaneo che si verifica durante la risoluzione dei nomi host e significa 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.
WSATYPE_NOT_FOUND	La classe specificata non è stata trovata. Il parametro pServiceName non è supportato per il membro ai_socktype specificato della struttura addrinfoW a cui punta il parametro hint.

Commenti

La funzione GetAddrInfoW è la versione Unicode di una funzione che fornisce la traduzione indipendente dal protocollo dal nome host all'indirizzo. La versione ANSI di questa funzione è getaddrinfo.

La funzione GetAddrInfoW restituisce i risultati per lo spazio dei nomi NS_DNS . La funzione GetAddrInfoW aggrega tutte le risposte se più provider di spazi dei nomi restituiscono informazioni. Per l'uso con il protocollo 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 per lo spazio dei nomi NS_DNS .

Le macro nel file di intestazione Winsock definiscono un nome di funzione mixed-case di GetAddrInfo e una struttura ADDRINFOT . Questa funzione GetAddrInfo deve essere chiamata con i parametri pNodeName e pServiceName di un puntatore di tipo TCHAR e i parametri pHints e ppResult di un puntatore di tipo ADDRINFOT. Quando viene definito UNICODE o _UNICODE, GetAddrInfo è definito per GetAddrInfoW, la versione Unicode della funzione e ADDRINFOT viene definita alla struttura addrinfoW. Quando UNICODE o _UNICODE non è definito, GetAddrInfo viene definito per ottenereaddrinfo, la versione ANSI della funzione e ADDRINFOT viene definita alla struttura addrinfo .

Uno o entrambi i parametri pNodeName o pServiceName devono puntare a una stringa Unicode con terminazione NULL; in genere vengono forniti entrambi.

Al termine dell'operazione, viene restituito un elenco collegato di strutture addrinfoW nel parametro ppResult . L'elenco può essere elaborato seguendo il puntatore fornito nel membro ai_next di ogni struttura addrinfoW restituita fino a quando non viene rilevato un puntatore NULL . In ogni struttura addrinfoW restituita, i ai_family, i ai_socktype e i membri ai_protocol corrispondono ai rispettivi argomenti in una chiamata di funzione socket o WSASocket . Inoltre, il membro ai_addr in ogni struttura addrinfoW restituita punta a una struttura di indirizzi socket compilata, la lunghezza di cui è specificato nel relativo membro ai_addrlen .

Se il parametro pNodeName punta a un nome computer, vengono restituiti tutti gli indirizzi permanenti per il computer che può essere usato come indirizzo di origine. In Windows Vista e versioni successive, questi indirizzi includono tutti gli indirizzi IP unicast restituiti dalla funzione GetUnicastIpAddressTable o GetUnicastIpAddressEntry 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 di 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 dalle funzioni GetUnicastIpAddressTable o GetUnicastIpAddressEntry in cui il membro SkipAsSource è impostato su true nella struttura MIB_UNICASTIPADDRESS_ROW . Per altre informazioni sul clustering, vedere Windows Clustering .

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. In questo modo viene modificato anche il comportamento in modo che se il membro SkipAsSource 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 l'impostazione dell'attributo SkipAsSource in un indirizzo IP. Questo hotfix modifica anche il comportamento in modo che se il membro SkipAsSource 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. Per altre informazioni, vedere knowledge base (KB) 2386184.

È disponibile anche un hotfix simile per Windows Vista con Service Pack 2 (SP2) e Windows Server 2008 con Service Pack 2 (SP2) 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 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.

I chiamanti della funzione GetAddrInfoW possono fornire suggerimenti sul tipo di socket supportato tramite una struttura addrinfoW a cui punta il parametro pHints . Quando si usa il parametro pHints , le regole seguenti si applicano alla struttura addrinfoW associata:

Un valore di 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.
Il valore 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 forniti nel parametro pHints indicano requisiti specifici. Ad esempio, se il chiamante gestisce solo IPv4 e non gestisce IPv6, il membro ai_family deve essere impostato su AF_INET. Per un altro esempio, se il chiamante gestisce solo TCP e non gestisce UDP, il membro ai_socktype deve essere impostato su SOCK_STREAM.

Se il parametro pHints è un puntatore NULL , la funzione GetAddrInfoW la gestisce come se la struttura addrinfoW in pHints fosse inizializzata con il relativo membro ai_family impostato su AF_UNSPEC e tutti gli altri membri impostati su zero.

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 può essere utilizzata per convertire una rappresentazione di stringa di testo di un indirizzo IP in una struttura addrinfoW che contiene una struttura sockaddr per l'indirizzo IP e altre informazioni. Per essere usata in questo modo, la stringa a cui punta il parametro pNodeName deve contenere una rappresentazione testuale di un indirizzo IP e la struttura addrinfoW a cui punta il parametro pHints deve essere impostato il flag AI_NUMERICHOST nel membro ai_flags . La stringa a cui punta il parametro pNodeName può contenere una rappresentazione testuale di un indirizzo IPv4 o IPv6. L'indirizzo IP di testo viene convertito in una struttura addrinfoW a cui punta il parametro ppResult . La struttura addrinfoW restituita contiene una struttura sockaddr per l'indirizzo IP insieme ad altre informazioni sull'indirizzo IP. Affinché questo metodo funzioni con una stringa di indirizzo IPv6 in Windows Server 2003 e Windows XP, il protocollo IPv6 deve essere installato nel computer locale. In caso contrario, viene restituito l'errore WSAHOST_NOT_FOUND .

Liberare le informazioni sugli indirizzi dall'allocazione dinamica

Tutte le informazioni restituite dalla funzione GetAddrInfoW a cui punta il parametro ppResult vengono allocate dinamicamente, incluse tutte le strutture addrinfoW , le strutture di indirizzi socket e le stringhe dei nomi host canonici a cui puntano le strutture addrinfoW . La memoria allocata da una chiamata riuscita a questa funzione deve essere rilasciata con una chiamata successiva a FreeAddrInfoW.

Codice di esempio

Nell'esempio di codice seguente viene illustrato come usare la funzione GetAddrInfoW .

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

Nota Assicurarsi che l'ambiente di sviluppo sia destinato alla versione più recente di Ws2tcpip.h , che include rispettivamente le definizioni di struttura e di funzione per addrinfoW e GetAddrInfoW.

Nomi di dominio internazionalizzati

I nomi host Internet sono in genere costituiti da un set di caratteri molto limitato:

Lettere ASCII maiuscole e minuscole dell'alfabeto inglese.
Cifre comprese tra 0 e 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 5890 e RFC 6365 pubblicate da Internet Engineering Task Force (IETF).

In Windows 8 e Windows Server 2012, la funzione GetAddrInfoW fornisce il supporto per l'analisi IDN (Internationalized Domain Name) applicata al nome passato nel parametro pNodeName . Winsock esegue la codifica e la conversione punycode/IDN. Questo comportamento può essere disabilitato usando il flag AI_DISABLE_IDN_ENCODING descritto di seguito.

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 non usa Punycode per convertire un IDN in base a RFC 3490. La funzione GetAddrInfoW durante l'esecuzione di query DNS codifica il nome Unicode in formato UTF-8, il formato usato dai server DNS Microsoft in un ambiente aziendale.

Diverse funzioni in Windows Vista e versioni successive supportano la conversione tra etichette Unicode in un IDN ai rispettivi 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 converte il formato ASCII di un IDN nella normale sintassi di codifica Unicode UTF-16. Per altre informazioni e collegamenti ai progetti di standard correlati, vedere Gestione dei nomi di dominio internazionalizzati (IDN).For more information and links to related draft standards, see Handling Internationalized Domain Names (IDN).

La funzione IdnToAscii può essere usata per convertire un nome IDN nel formato ASCII. Per passare questo modulo ASCII alla funzione GetAddrInfoW , è possibile utilizzare la funzione MultiByteToWideChar per convertire la stringa CHAR in una stringa WCHAR che può quindi essere passata nel parametro pNodeName alla funzione GetAddrInfoW .

Uso di ai_flags nel parametro hints

I flag nel membro ai_flags della struttura addrinfoW facoltativa fornita nel parametro pHints modificano 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 Platform Software Development Kit (SDK) per Windows Server 2003 e Windows XP.

I bit del flag possono essere una combinazione dei seguenti:

Flag Bits	Descrizione
AI_PASSIVE	L'impostazione del flag AI_PASSIVE indica che il chiamante intende utilizzare la struttura di indirizzi socket restituita in una chiamata alla funzione di associazione . Quando il flag AI_PASSIVE è impostato e pNodeName è un puntatore NULL , la parte dell'indirizzo IP della struttura degli indirizzi socket viene impostata su INADDR_ANY per gli indirizzi IPv4 e IN6ADDR_ANY_INIT per gli indirizzi IPv6. Quando il flag di AI_PASSIVE non è impostato, la struttura di indirizzi socket restituita è pronta per una chiamata alla funzione di connessione per un protocollo orientato alla connessione o pronta per una chiamata alle funzioni connect, sendto o send per un protocollo senza connessione.When the AI_PASSIVE flag is not set, the returned socket address structure is ready for a connectionless protocol, or ready for a connect, sendto, or send functions for a connectionless protocol. Se il parametro pNodeName è un puntatore NULL in questo caso, la parte dell'indirizzo IP della struttura di indirizzi socket viene impostata sull'indirizzo di loopback.
AI_CANONNAME	Se non viene usato né AI_CANONNAME néAI_NUMERICHOST , la funzione GetAddrInfoW tenta la risoluzione. Se una stringa letterale viene passata a GetAddrInfoW tenta di convertire la stringa e se un nome host viene passato alla funzione GetAddrInfoW tenta di risolvere il nome in un indirizzo o in più indirizzi. 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 con terminazione NULL che contiene il nome canonico del nodo specificato. Nota La funzione GetAddrInfoW può restituire l'esito positivo quando il flag AI_CANONNAME è impostato, ma il membro ai_canonname nella struttura addrinfoW associata è NULL. Pertanto, l'uso consigliato del flag di AI_CANONNAME include il test se il membro ai_canonname nella struttura addrinfoW associata è NULL.
AI_NUMERICHOST	Quando il bit AI_NUMERICHOST è impostato, il parametro pNodeName deve contenere una stringa di indirizzo host numerico non NULL . 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 AI_NUMERICSERV è impostato, il parametro pServiceName deve contenere un numero di porta numerico non NULL . In caso contrario, viene restituito l'errore di EAI_NONAME . Questo flag impedisce la chiamata di un servizio di risoluzione dei nomi. 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 indirizzi IPv6 e indirizzi IPv4 con AI_V4MAPPED. Il flag di AI_ALL viene definito in Windows SDK per Windows Vista e versioni successive. Il flag di AI_ALL è supportato in Windows Vista e versioni successive.
AI_ADDRCONFIG	Se il bit di AI_ADDRCONFIG è impostato, GetAddrInfoW risolverà solo se è configurato un indirizzo globale. Se viene specificato AI_ADDRCONFIG flag, gli indirizzi IPv4 verranno restituiti solo se un indirizzo IPv4 è configurato nel sistema locale e gli indirizzi IPv6 verranno restituiti solo se un indirizzo IPv6 è configurato nel sistema locale. 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 eseguita una richiesta di servizio dei nomi per gli indirizzi IPv4 e questi indirizzi vengono convertiti in formato indirizzi IPv4 mappati. Il flag di AI_V4MAPPED viene 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 di AI_NON_AUTHORITATIVE è impostato, il provider di spazi dei nomi NS_EMAIL restituisce risultati autorevoli e non autorevoli. Se il bit di AI_NON_AUTHORITATIVE non è impostato, il provider di spazi 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 di AI_SECURE è impostato, il provider di spazi dei nomi NS_EMAIL restituirà i risultati ottenuti con sicurezza avanzata per ridurre al minimo il possibile 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 il AI_RETURN_PREFERRED_NAMES è impostato, non è necessario specificare alcun nome nel parametro pNodeName . Il provider di spazi dei nomi NS_EMAIL restituirà nomi preferiti per la pubblicazione. Il flag AI_RETURN_PREFERRED_NAMES viene definito in Windows SDK per Windows Vista e versioni successive. Il flag di AI_RETURN_PREFERRED_NAMES è supportato in Windows Vista e versioni successive e si applica solo allo spazio dei nomi NS_EMAIL .
AI_FQDN	Se la AI_FQDN è impostata e viene specificato un nome flat (etichetta singola), GetAddrInfoW restituirà il nome di dominio completo a cui il nome verrà risolto. Il nome di dominio completo viene restituito nel membro ai_canonname nella struttura addrinfoW associata. Questo è diverso dal flag di bit AI_CANONNAME che restituisce il nome canonico registrato in DNS, che può essere diverso dal nome di dominio completo a cui è stato risolto il nome flat. È possibile impostare solo uno dei AI_FQDN e AI_CANONNAME bit. La funzione GetAddrInfoW avrà esito negativo se entrambi i flag sono presenti con EAI_BADFLAGS. Quando il bit di AI_FQDN è impostato, il parametro pNodeName non può essere NULL. In caso contrario, la funzione GetAddrInfoEx avrà esito negativo con WSANO_RECOVERY. 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 il AI_FILESERVER è impostato, si tratta di un hint per il provider di spazi dei nomi in cui viene eseguita la query del nome host nello scenario di condivisione file. Il provider di spazi dei nomi può ignorare questo hint. Windows 7: Il flag AI_FILESERVER è definito in Windows SDK per Windows 7 e versioni successive. Il flag di AI_FILESERVER è supportato in Windows 7 e versioni successive.
AI_DISABLE_IDN_ENCODING	Se la AI_DISABLE_IDN_ENCODING è impostata, questa disabilita la codifica nome dominio internazionale automatica usando Punycode nelle funzioni di risoluzione dei nomi chiamate dalla funzione 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

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	Windows
Intestazione	ws2tcpip.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll