Funzione getaddrinfo (ws2tcpip.h)

Articolo
03/04/2024

La funzione getaddrinfo fornisce una conversione indipendente dal protocollo da un nome host ANSI a un indirizzo.

Sintassi

INT WSAAPI getaddrinfo(
  [in, optional] PCSTR           pNodeName,
  [in, optional] PCSTR           pServiceName,
  [in, optional] const ADDRINFOA *pHints,
  [out]          PADDRINFOA      *ppResult
);

Parametri

[in, optional] pNodeName

Puntatore a una stringa ANSI con terminazione NULL 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 punteggiato-decimale o un indirizzo esadecimale IPv6.

[in, optional] pServiceName

Puntatore a una stringa ANSI con terminazione NULL contenente un nome di 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 viene specificato un numero di porta sono elencati nel file seguente:

%WINDIR%\system32\drivers\etc\services

[in, optional] pHints

Puntatore a una struttura addrinfo che fornisce suggerimenti sul tipo di socket supportato dal chiamante.

I membri ai_addrlen, ai_canonname, ai_addr e ai_next della struttura addrinfo 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 la sezione Osservazioni.

[out] ppResult

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

Valore restituito

L'operazione riuscita 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 diversi da zero restituiti dalla funzione getaddrinfo è mappato al set di errori descritti dalle raccomandazioni di Internet Engineering Task Force (IETF). La tabella seguente elenca 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.

Valore di errore	Equivalente WSA	Descrizione
EAI_AGAIN	WSATRY_AGAIN	Si è verificato un errore temporaneo nella risoluzione dei nomi.
EAI_BADFLAGS	WSAEINVAL	È stato specificato un valore non valido per il membro ai_flags del parametro pHints .
EAI_FAIL	WSANO_RECOVERY	Si è verificato un errore irreversibile nella risoluzione dei nomi.
EAI_FAMILY	WSAEAFNOSUPPORT	Il membro ai_family 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 non sono stati forniti i parametri pNodeName e pServiceName .
EAI_SERVICE	WSATYPE_NOT_FOUND	Il parametro pServiceName non è supportato per il membro ai_socktype specificato del parametro pHints .
EAI_SOCKTYPE	WSAESOCKTNOSUPPORT	Il membro ai_socktype del parametro pHints non è supportato.

Usare la funzione gai_strerror per stampare i messaggi di errore in base ai codici EAI restituiti dalla funzione getaddrinfo . 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 .

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 addrinfo a cui punta il parametro pHints non è supportato.
WSAEINVAL	Argomento fornito non valido. Questo errore viene restituito se è stato specificato un valore non valido per il membro ai_flags della struttura addrinfo a cui punta il parametro pHints .
WSAESOCKTNOSUPPORT	Il supporto per il tipo di socket specificato non esiste in questa famiglia di indirizzi. Questo errore viene restituito se il membro ai_socktype della struttura addrinfo a cui punta il parametro pHints 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 forniti.
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 irreversibile nella risoluzione dei nomi.
WSANOTINITIALISED	Prima di usare questa funzione, è necessario che venga eseguita 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 addrinfo a cui punta il parametro pHints .

Commenti

La funzione getaddrinfo è la versione ANSI di una funzione che fornisce una conversione indipendente dal protocollo dal nome host all'indirizzo. La versione Unicode di questa funzione è GetAddrInfoW. Gli sviluppatori sono invitati a usare la funzione Unicode GetAddrInfoW anziché la funzione ANSI getaddrinfo .

La funzione getaddrinfo restituisce i risultati per lo spazio dei nomi NS_DNS . La funzione getaddrinfo 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 eseguita dal dns (Domain Name System), da un file host locale o da altri meccanismi di denominazione per lo spazio dei nomi NS_DNS .

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

Le macro nel file di intestazione Ws2tcpip.h definiscono un nome di funzione con maiuscole e minuscole 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 UNICODE o _UNICODE non è definito, GetAddrInfo viene definito per getaddrinfo, la versione ANSI della funzione e ADDRINFOT viene definita per la struttura addrinfo . Quando viene definito UNICODE o _UNICODE , GetAddrInfo viene definito in GetAddrInfoW, la versione Unicode della funzione e ADDRINFOT viene definita per la struttura addrinfoW .

I nomi dei parametri e i tipi di parametro per la funzione getaddrinfo definiti nel file di intestazione Ws2tcpip.h nel Platform Software Development Kit (SDK) per Windows Server 2003 e Windows XP erano diversi.

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

Al termine dell'operazione, viene restituito un elenco collegato di strutture addrinfo nel parametro ppResult . L'elenco può essere elaborato seguendo il puntatore fornito nel membro ai_next di ogni struttura addrinfo restituita fino a quando non viene rilevato un puntatore NULL . In ogni struttura addrinfo restituita, i membri ai_family, ai_socktype e ai_protocol corrispondono ai rispettivi argomenti in una chiamata di funzione socket o WSASocket . Inoltre, il membro ai_addr in ogni struttura addrinfo restituita punta a una struttura di indirizzi socket compilata, la cui lunghezza viene specificata 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 dalle funzioni 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 getaddrinfo possono fornire suggerimenti sul tipo di socket supportato tramite una struttura addrinfo a cui punta il parametro pHints . Quando si usa il parametro pHints , le regole seguenti si applicano alla struttura addrinfo 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.

Un valore di AF_UNSPEC per ai_family indica che il chiamante accetterà qualsiasi famiglia di protocolli. Questo valore può essere usato per restituire indirizzi IPv4 e IPv6 per il nome host a cui punta il parametro pNodeName . In Windows Server 2003 e Windows XP, gli indirizzi IPv6 vengono restituiti solo se IPv6 è installato nel computer locale.

Altri valori nella struttura addrinfo 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 getaddrinfo la considera come se la struttura addrinfo 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 getaddrinfo 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 getaddrinfo può essere usata per convertire una rappresentazione di stringa di testo di un indirizzo IP in una struttura addrinfo contenente 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 addrinfo 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 addrinfo a cui punta il parametro ppResult . La struttura addrinfo restituita contiene una struttura sockaddr per l'indirizzo IP insieme alle informazioni aggiuntive 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 getaddrinfo a cui punta il parametro ppResult vengono allocate dinamicamente, incluse tutte le strutture addrinfo , le strutture di indirizzi socket e le stringhe dei nomi host canonici a cui puntano le strutture addrinfo . La memoria allocata da una chiamata riuscita a questa funzione deve essere rilasciata con una chiamata successiva a freeaddrinfo.

Codice di esempio

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

#undef UNICODE

#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;
    INT iRetval;

    DWORD dwRetval;

    int i = 1;
    
    struct addrinfo *result = NULL;
    struct addrinfo *ptr = NULL;
    struct addrinfo hints;

    struct sockaddr_in  *sockaddr_ipv4;
//    struct sockaddr_in6 *sockaddr_ipv6;
    LPSOCKADDR sockaddr_ip;

    char ipstringbuffer[46];
    DWORD ipbufferlength = 46;

    // Validate the parameters
    if (argc != 3) {
        printf("usage: %s <hostname> <servicename>\n", argv[0]);
        printf("getaddrinfo provides protocol-independent translation\n");
        printf("   from an ANSI host name to an IP address\n");
        printf("%s example usage\n", argv[0]);
        printf("   %s www.contoso.com 0\n", argv[0]);
        return 1;
    }

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("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;

    printf("Calling getaddrinfo with following parameters:\n");
    printf("\tnodename = %s\n", argv[1]);
    printf("\tservname (or port) = %s\n\n", argv[2]);
    
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
    dwRetval = getaddrinfo(argv[1], argv[2], &hints, &result);
    if ( dwRetval != 0 ) {
        printf("getaddrinfo failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }

    printf("getaddrinfo returned success\n");
    
    // Retrieve each address and print out the hex bytes
    for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {

        printf("getaddrinfo response %d\n", i++);
        printf("\tFlags: 0x%x\n", ptr->ai_flags);
        printf("\tFamily: ");
        switch (ptr->ai_family) {
            case AF_UNSPEC:
                printf("Unspecified\n");
                break;
            case AF_INET:
                printf("AF_INET (IPv4)\n");
                sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
                printf("\tIPv4 address %s\n",
                    inet_ntoa(sockaddr_ipv4->sin_addr) );
                break;
            case AF_INET6:
                printf("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)
                    printf("WSAAddressToString failed with %u\n", WSAGetLastError() );
                else    
                    printf("\tIPv6 address %s\n", ipstringbuffer);
                break;
            case AF_NETBIOS:
                printf("AF_NETBIOS (NetBIOS)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_family);
                break;
        }
        printf("\tSocket type: ");
        switch (ptr->ai_socktype) {
            case 0:
                printf("Unspecified\n");
                break;
            case SOCK_STREAM:
                printf("SOCK_STREAM (stream)\n");
                break;
            case SOCK_DGRAM:
                printf("SOCK_DGRAM (datagram) \n");
                break;
            case SOCK_RAW:
                printf("SOCK_RAW (raw) \n");
                break;
            case SOCK_RDM:
                printf("SOCK_RDM (reliable message datagram)\n");
                break;
            case SOCK_SEQPACKET:
                printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_socktype);
                break;
        }
        printf("\tProtocol: ");
        switch (ptr->ai_protocol) {
            case 0:
                printf("Unspecified\n");
                break;
            case IPPROTO_TCP:
                printf("IPPROTO_TCP (TCP)\n");
                break;
            case IPPROTO_UDP:
                printf("IPPROTO_UDP (UDP) \n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_protocol);
                break;
        }
        printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
        printf("\tCanonical name: %s\n", ptr->ai_canonname);
    }

    freeaddrinfo(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 addrinfo e getaddrinfo.

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 getaddrinfo 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 getaddrinfo attualmente non fornisce supporto per l'analisi IDN applicata al nome passato nel parametro pNodeName . Winsock non esegue alcuna conversione Punycode/IDN. La versione a caratteri wide della funzione GetAddrInfo non usa Punycode per convertire un IDN in base a RFC 3490. La versione a caratteri wide della funzione GetAddrInfo 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 modulo ASCII che può quindi essere passato nel parametro pNodeName alla funzione getaddrinfo . Per passare questo nome IDN alla funzione GetAddrInfo quando viene usata la versione a caratteri wide di questa funzione (quando viene definito UNICODE o _UNICODE), è possibile usare la funzione MultiByteToWideChar per convertire la stringa CHAR in una stringa WCHAR .

Uso di ai_flags nel parametro pHints

I flag nel membro ai_flags della struttura addrinfo 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 in Platform 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 getaddrinfo tenta la risoluzione. Se viene passata una stringa letterale getaddrinfo tenta di convertire la stringa e se un nome host viene passato alla funzione getaddrinfo 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 getaddrinfo avrà esito negativo con WSANO_RECOVERY. Quando il bit AI_CANONNAME è impostato e la funzione getaddrinfo 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 getaddrinfo può restituire l'esito positivo quando il flag AI_CANONNAME è impostato, ma il membro ai_canonname nella struttura addrinfo associata è NULL. Pertanto, l'uso consigliato del flag AI_CANONNAME include il test se il membro ai_canonname nella struttura addrinfo 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 AI_ALL viene 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, getaddrinfo verrà risolto solo se è configurato un indirizzo globale. Se viene specificato AI_ADDRCONFIG flag, gli indirizzi IPv4 verranno restituiti solo se è configurato un indirizzo IPv4 nel sistema locale 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 viene 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 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 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 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 il possibile spoofing. Il flag AI_SECURE viene 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 deve essere specificato alcun nome nel parametro pNodeName . Il provider dello spazio dei nomi NS_EMAIL restituirà i nomi preferiti per la pubblicazione. Il flag AI_RETURN_PREFERRED_NAMES viene 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), getaddrinfo 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 addrinfo associata. Questo è diverso da AI_CANONNAME flag di bit che restituisce il nome canonico registrato in DNS, che può essere diverso dal nome di dominio completo risolto dal nome flat. È possibile impostare solo uno dei bit di AI_FQDN e AI_CANONNAME . La funzione getaddrinfo avrà esito negativo se entrambi i flag sono presenti con EAI_BADFLAGS. Quando il bit 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 suggerimento per il provider dello spazio dei nomi su cui viene eseguita la query sul nome host sottoposto a query nello scenario di condivisione file. Il provider dello spazio dei nomi può ignorare questo hint. Windows 7: Il flag AI_FILESERVER viene definito in Windows SDK per Windows 7 e versioni successive. Il flag AI_FILESERVER è supportato in Windows 7 e versioni successive.

Codice di esempio con AI_NUMERICHOST

Nell'esempio di codice seguente viene illustrato come usare la funzione getaddrinfo per convertire una rappresentazione di stringa di testo di un indirizzo IP in una struttura addrinfo contenente una struttura sockaddr per l'indirizzo IP e altre informazioni.

#undef UNICODE

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

    int i = 1;
    
    struct addrinfo *result = NULL;
    struct addrinfo *ptr = NULL;
    struct addrinfo hints;


    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s <IP Address String>\n", argv[0]);
        printf("  getaddrinfo determines the IP binary network address\n");
        printf("       %s 207.46.197.32\n", argv[0]);  /* www.contoso.com */
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("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_flags = AI_NUMERICHOST;
    hints.ai_family = AF_UNSPEC;
//    hints.ai_socktype = SOCK_STREAM;
//    hints.ai_protocol = IPPROTO_TCP;


//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
    dwRetval = getaddrinfo(argv[1], NULL, &hints, &result);
    if ( dwRetval != 0 ) {
        printf("getaddrinfo failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }

    printf("getaddrinfo returned success\n");
    
    // Retrieve each address and print out the hex bytes
    for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {

        printf("getaddrinfo response %d\n", i++);
        printf("\tFlags: 0x%x\n", ptr->ai_flags);
        printf("\tFamily: ");
        switch (ptr->ai_family) {
            case AF_UNSPEC:
                printf("Unspecified\n");
                break;
            case AF_INET:
                printf("AF_INET (IPv4)\n");
                break;
            case AF_INET6:
                printf("AF_INET6 (IPv6)\n");
                break;
            case AF_NETBIOS:
                printf("AF_NETBIOS (NetBIOS)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_family);
                break;
        }
        printf("\tSocket type: ");
        switch (ptr->ai_socktype) {
            case 0:
                printf("Unspecified\n");
                break;
            case SOCK_STREAM:
                printf("SOCK_STREAM (stream)\n");
                break;
            case SOCK_DGRAM:
                printf("SOCK_DGRAM (datagram) \n");
                break;
            case SOCK_RAW:
                printf("SOCK_RAW (raw) \n");
                break;
            case SOCK_RDM:
                printf("SOCK_RDM (reliable message datagram)\n");
                break;
            case SOCK_SEQPACKET:
                printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_socktype);
                break;
        }
        printf("\tProtocol: ");
        switch (ptr->ai_protocol) {
            case 0:
                printf("Unspecified\n");
                break;
            case IPPROTO_TCP:
                printf("IPPROTO_TCP (TCP)\n");
                break;
            case IPPROTO_UDP:
                printf("IPPROTO_UDP (UDP) \n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_protocol);
                break;
        }
        printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
        printf("\tCanonical name: %s\n", ptr->ai_canonname);
    }

    freeaddrinfo(result);
    WSACleanup();

    return 0;
}

Supporto per getaddrinfo in Windows 2000 e versioni precedenti

La funzione getaddrinfo è stata aggiunta al Ws2_32.dll in Windows XP e versioni successive. Per eseguire un'applicazione che usa questa funzione nelle versioni precedenti di Windows, è necessario includere i file Ws2tcpip.h e Wspiapi.h . Quando viene aggiunto il file di inclusione Wspiapi.h , la funzione getaddrinfo viene definita alla funzione inline WspiapiGetAddrInfo nel file Wspiapi.h . In fase di esecuzione, la funzione WspiapiGetAddrInfo viene implementata in modo che se il Ws2_32.dll o il Wship6.dll (il file contenente getaddrinfo nell'anteprima della tecnologia IPv6 per Windows 2000) non include getaddrinfo, una versione di getaddrinfo viene implementata inline in base al codice nel file di intestazione Wspiapi.h. Questo codice inline verrà usato nelle piattaforme Windows precedenti che non supportano in modo nativo la funzione getaddrinfo .

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

La funzione GetAddrInfoW è la versione Unicode di getaddrinfo. La funzione GetAddrInfoW è stata aggiunta al Ws2_32.dll in Windows XP con Service Pack 2 (SP2). La funzione GetAddrInfoW non può essere utilizzata nelle versioni di Windows precedenti a Windows XP con SP2.

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.

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