Struttura ADDRINFOEXW (ws2def.h)

La struttura addrinfoex viene utilizzata dalla funzione GetAddrInfoEx per contenere le informazioni sull'indirizzo host.

Sintassi

typedef struct addrinfoexW {
  int                ai_flags;
  int                ai_family;
  int                ai_socktype;
  int                ai_protocol;
  size_t             ai_addrlen;
  PWSTR              ai_canonname;
  struct sockaddr    *ai_addr;
  void               *ai_blob;
  size_t             ai_bloblen;
  LPGUID             ai_provider;
  struct addrinfoexW *ai_next;
} ADDRINFOEXW, *PADDRINFOEXW, *LPADDRINFOEXW;

Members

ai_flags

Tipo: int

Flag che indicano le opzioni usate nella funzione GetAddrInfoEx .

I valori supportati per il membro ai_flags sono definiti nel file di inclusione Winsock2.h e possono essere una combinazione delle opzioni seguenti.

Valore Significato
AI_PASSIVE
0x01
L'indirizzo del socket verrà usato in una chiamata alla funzione di associazione .
AI_CANONNAME
0x02
Il nome canonico viene restituito nel primo membro ai_canonname .

Quando vengono impostati sia il AI_CANONNAME che i bit AI_FQDN , viene restituita una struttura addrinfoex2 non la struttura addrinfoex .

AI_NUMERICHOST
0x04
Il parametro nodename passato alla funzione GetAddrInfoEx deve essere una stringa numerica.
AI_ALL
0x0100
Se questo bit è impostato, viene effettuata una richiesta per gli indirizzi IPv6 e gli indirizzi IPv4 con AI_V4MAPPED.

Questa opzione è supportata in Windows Vista e versioni successive.

AI_ADDRCONFIG
0x0400
GetAddrInfoEx verrà risolto solo se è configurato un indirizzo globale. L'indirizzo di loopback IPv6 e IPv4 non è considerato un indirizzo globale valido.

Questa opzione è supportata solo in Windows Vista e versioni successive.

AI_V4MAPPED
0x0800
Se la richiesta GetAddrInfoEx per 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.

Questa opzione è supportata in Windows Vista e versioni successive.

AI_NON_AUTHORITATIVE
0x04000
Le informazioni sull'indirizzo provengono da risultati non autorevoli.

Quando questa opzione viene impostata nel parametro pHints di GetAddrInfoEx, il provider dello spazio dei nomi NS_EMAIL restituisce risultati autorevoli e non autorevoli. Se questa opzione non è impostata, vengono restituiti solo i risultati autorevoli.

Nel parametro ppResults restituito da GetAddrInfoEx questo flag viene impostato nel membro ai_flags della struttura addrinfoex per risultati non autorevoli.

Questa opzione è supportata solo in Windows Vista e versioni successive per lo spazio dei nomi NS_EMAIL .

AI_SECURE
0x08000
Le informazioni sull'indirizzo provengono da un canale sicuro. 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.

Quando questa opzione viene impostata nel parametro pHints di GetAddrInfoEx, il provider dello spazio dei nomi NS_EMAIL restituisce solo i risultati ottenuti con sicurezza avanzata per ridurre al minimo il possibile spoofing.

Nel parametro ppResults restituito da GetAddrInfoEx, questo flag viene impostato nel membro ai_flags della struttura addrinfoex per i risultati restituiti con sicurezza avanzata per ridurre al minimo il possibile spoofing.

Questa opzione è supportata solo in Windows Vista e versioni successive per lo spazio dei nomi NS_EMAIL .

AI_RETURN_PREFERRED_NAMES
0x010000
Le informazioni sull'indirizzo sono relative a nomi preferiti per la pubblicazione con uno spazio dei nomi specifico.

Quando questa opzione viene impostata nel parametro pHints di GetAddrInfoEx, non deve essere specificato alcun nome nel parametro pName e il provider dello spazio dei nomi NS_EMAIL restituirà i nomi preferiti per la pubblicazione.

Nel parametro ppResults restituito da GetAddrInfoEx questo flag viene impostato nel membro ai_flags della struttura addrinfoex per i risultati restituiti per i nomi preferiti per la pubblicazione.

Questa opzione è supportata solo in Windows Vista e versioni successive per lo spazio dei nomi NS_EMAIL .

AI_FQDN
0x00020000
Il nome di dominio completo viene restituito nel primo membro ai_canonicalname .

Quando questa opzione viene impostata nel parametro pHints di GetAddrInfoEx e viene specificato un nome flat (etichetta singola) nel parametro pName , verrà restituito il nome di dominio completo che il nome ha risolto.

Quando vengono impostati sia il AI_CANONNAME che i bit AI_FQDN , viene restituita una struttura addrinfoex2 non la struttura addrinfoex .

Questa opzione è supportata in Windows 7, Windows Server 2008 R2 e versioni successive.

AI_FILESERVER
0x00040000
Suggerimento per il provider dello spazio dei nomi su cui viene eseguita la query sul nome host in uno scenario di condivisione file. Il provider dello spazio dei nomi può ignorare questo hint.

Questa opzione è supportata in Windows 7, Windows Server 2008 R2 e versioni successive.

AI_DISABLE_IDN_ENCODING
0x00080000
Disabilitare la codifica automatica dei nomi di dominio internazionale usando Punycode nelle funzioni di risoluzione dei nomi chiamate dalla funzione GetAddrInfoEx .

Questa opzione è supportata in Windows 8, Windows Server 2012 e versioni successive.

ai_family

Tipo: int

Famiglia di indirizzi. I valori possibili per la famiglia di indirizzi sono definiti nel file di inclusione Winsock2.h .

Nella Windows SDK rilasciata per Windows Vista e versioni successive, l'organizzazione dei file di intestazione è stata modificata e i valori possibili per la famiglia di indirizzi sono definiti nel file di intestazione Ws2def.h. Si noti che il file di intestazione Ws2def.h viene automaticamente incluso in Winsock2.h e non deve mai essere usato direttamente.

I valori attualmente supportati sono AF_INET o AF_INET6, ovvero i formati della famiglia di indirizzi Internet per IPv4 e IPv6. Altre opzioni per la famiglia di indirizzi (AF_NETBIOS per l'uso con NetBIOS, ad esempio) sono supportate se è installato un provider di servizi Windows Sockets per la famiglia di indirizzi. Si noti che i valori per la famiglia di indirizzi AF_ e le costanti della famiglia di protocolli PF_ sono identiche (ad esempio, AF_UNSPEC e PF_UNSPEC), quindi è possibile usare entrambe le costanti.

La tabella seguente elenca i valori comuni per la famiglia di indirizzi anche se sono possibili molti altri valori.

Valore Significato
AF_UNSPEC
0
La famiglia di indirizzi non è specificata.
AF_INET
2
Famiglia di indirizzi IPv4 (Internet Protocol versione 4).
AF_NETBIOS
17
Famiglia di indirizzi NetBIOS. Questa famiglia di indirizzi è supportata solo se è installato un provider Windows Sockets per NetBIOS.
AF_INET6
23
Famiglia di indirizzi IPv6 (Internet Protocol versione 6).
AF_IRDA
26
Famiglia di indirizzi IrDA (Infrared Data Association). Questa famiglia di indirizzi è supportata solo se nel computer è installata una porta e un driver a infrarossi.
AF_BTH
32
Famiglia di indirizzi Bluetooth. Questa famiglia di indirizzi è supportata solo se un adattatore Bluetooth è installato in Windows Server 2003 o versione successiva.

ai_socktype

Tipo: int

Tipo di socket. I valori possibili per il tipo di socket sono definiti nel file di inclusione Winsock2.h .

Nella tabella seguente sono elencati i valori possibili per il tipo di socket supportato per Windows Sockets 2:

Valore Significato
SOCK_STREAM
1
Fornisce flussi di byte basati su byte sequenziati, affidabili e bidirezionali con un meccanismo di trasmissione dati OOB. Usa il protocollo TCP (Transmission Control Protocol) per la famiglia di indirizzi Internet (AF_INET o AF_INET6). Se il membro ai_family è AF_IRDA, SOCK_STREAM è l'unico tipo di socket supportato.
SOCK_DGRAM
2
Supporta i datagrammi, che non sono di connessione, buffer non affidabili di una lunghezza massima fissa (in genere piccola). Usa il protocollo UDP (User Datagram Protocol) per la famiglia di indirizzi Internet (AF_INET o AF_INET6).
SOCK_RAW
3
Fornisce un socket non elaborato che consente a un'applicazione di modificare l'intestazione del protocollo superiore superiore successiva. Per modificare l'intestazione IPv4, l'opzione socket IP_HDRINCL deve essere impostata sul socket. Per modificare l'intestazione IPv6, è necessario impostare l'opzione socket IPV6_HDRINCL sul socket.
SOCK_RDM
4
Fornisce un datagram di messaggi affidabile. Un esempio di questo tipo è l'implementazione del protocollo multicast (PGM) pragmatico in Windows, spesso definita programmazione multicast affidabile.
SOCK_SEQPACKET
5
Fornisce un pacchetto pseudo-stream basato su datagrammi.
 

In Windows Sockets 2 sono stati introdotti nuovi tipi di socket. Un'applicazione può individuare dinamicamente gli attributi di ogni protocollo di trasporto disponibile tramite la funzione WSAEnumProtocols . Un'applicazione può quindi determinare le possibili opzioni di socket e protocollo per una famiglia di indirizzi e usare queste informazioni quando si specifica questo parametro. Le definizioni dei tipi di socket nei file di intestazione Winsock2.h e Ws2def.h verranno aggiornate periodicamente come nuovi tipi di socket, famiglie di indirizzi e protocolli sono definiti.

In Windows Sockets 1.1, gli unici tipi di socket possibili sono SOCK_DATAGRAM e SOCK_STREAM.

ai_protocol

Tipo: int

Tipo di protocollo. Le opzioni possibili sono specifiche per la famiglia di indirizzi e il tipo di socket specificati. I valori possibili per la ai_protocol sono definiti in Winsock2.h e nei file di intestazione Wsrm.h .

Nella Windows SDK rilasciata per Windows Vista e versioni successive, l'organizzazione dei file di intestazione è stata modificata e questo membro può essere uno dei valori del tipo di enumerazione IPPROTO definito nel file di intestazione Ws2def.h. Si noti che il file di intestazione Ws2def.h viene incluso automaticamente in Winsock2.h e non deve mai essere usato direttamente.

Se viene specificato un valore pari a 0 per ai_protocol, il chiamante non vuole specificare un protocollo e il provider di servizi sceglierà il ai_protocol da usare. Per i protocolli diversi da IPv4 e IPv6, impostare ai_protocol su zero.

La tabella seguente elenca i valori comuni per il membro ai_protocol anche se sono possibili molti altri valori.

Valore Significato
IPPROTO_TCP
6
Protocollo TCP (Transmission Control Protocol). Si tratta di un valore possibile quando il membroai_family è AF_INET o AF_INET6 e il membro ai_socktype è SOCK_STREAM.
IPPROTO_UDP
17
Protocollo UDP (User Datagram Protocol). Si tratta di un valore possibile quando il membro ai_family è AF_INET o AF_INET6 e il parametro di tipo è SOCK_DGRAM.
IPPROTO_RM
113
Protocollo PGM per multicast affidabile. Si tratta di un valore possibile quando il membro ai_family è AF_INET e il membro ai_socktype è SOCK_RDM. Nel Windows SDK rilasciato per Windows Vista e versioni successive, questo valore viene chiamato anche IPPROTO_PGM.
 

Se il membro ai_family è AF_IRDA, il ai_protocol deve essere 0.

ai_addrlen

Tipo: size_t

Lunghezza, in byte, del buffer a cui punta il membro ai_addr .

ai_canonname

Tipo: PCTSTR

Nome canonico per l'host.

ai_addr

Tipo: struct sockaddr*

Puntatore a una struttura sockaddr . Il ai_addr membro in ogni struttura addrinfoex restituita punta a una struttura di indirizzi socket compilata. La lunghezza, in byte, di ogni struttura addrinfoex restituita viene specificata nel membro ai_addrlen .

ai_blob

Tipo: void*

Puntatore ai dati usati per restituire informazioni sullo spazio dei nomi specifiche del provider associate al nome oltre un elenco di indirizzi. La lunghezza, in byte, del buffer a cui punta ai_blob deve essere specificata nel membro ai_bloblen .

ai_bloblen

Tipo: size_t

Lunghezza, in byte, del membro ai_blob .

ai_provider

Tipo: LPGUID

Puntatore al GUID di un provider di spazi dei nomi specifico.

ai_next

Tipo: struct addrinfoex*

Puntatore alla struttura successiva in un elenco collegato. Questo parametro è impostato su NULL nell'ultima struttura addrinfoex di un elenco collegato.

Commenti

La struttura addrinfoex viene usata dalla funzione GetAddrInfoEx per contenere le informazioni sull'indirizzo host. La struttura addrinfoex è una versione avanzata delle strutture addrinfo e addrinfoW. I membri di struttura aggiuntivi sono per i dati BLOB e il GUID per il provider di spazi dei nomi. I dati BLOB vengono usati per restituire informazioni dello spazio dei nomi specifiche del provider aggiuntive associate a un nome. Il formato dei dati nel membro ai_blob è specifico per un determinato provider di spazi dei nomi. Attualmente, i dati BLOB vengono usati dal provider di spazi dei nomi NS_EMAIL per fornire informazioni aggiuntive.

La struttura addrinfoex è una versione avanzata della struttura addrinfo e addrinfoW usata con la funzione GetAddrInfoEx. La funzione GetAddrInfoEx consente di specificare il provider di spazi dei nomi per risolvere la query. 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, da un provider di posta elettronica (lo spazio dei nomi NS_EMAIL ) o da altri meccanismi di denominazione.

Quando unicode o _UNICODE è definito, addrinfoex viene definito per aggiungererinfoexW, la versione Unicode di questa struttura. I parametri stringa vengono definiti per il tipo di dati PWSTR e viene usata la struttura addrinfoexW .

Quando UNICODE o _UNICODE non è definito, addrinfoex viene definito per aggiungererinfoexA, la versione ANSI di questa struttura. I parametri stringa sono del tipo di dati PCSTR e viene usata la struttura addrinfoexA .

Dopo una chiamata riuscita a GetAddrInfoEx, viene restituito un elenco collegato di strutture addrinfoex nel parametro ppResult passato alla funzione GetAddrInfoEx . L'elenco può essere elaborato seguendo il puntatore fornito nel membro ai_next di ogni struttura addrinfoex restituita finché non viene rilevato un puntatore NULL . In ogni struttura addrinfoex 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 addrinfoex restituita punta a una struttura di indirizzi socket compilata, la lunghezza di cui è specificato nel relativo membro ai_addrlen .

Esempio

Nell'esempio seguente viene illustrato l'uso della struttura addrinfoex .


#ifndef UNICODE
#define UNICODE
#endif

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

#pragma comment(lib, "Ws2_32.lib")

int __cdecl wmain(int argc, wchar_t ** argv)
{
//--------------------------------
// Declare and initialize variables.
    WSADATA wsaData;
    int iResult;

    ADDRINFOEX *result = NULL;
    ADDRINFOEX *ptr = NULL;
    ADDRINFOEX hints;

    DWORD dwRetval = 0;
    int i = 1;

    DWORD dwNamespace = NS_DNS;
    LPGUID lpNspid = NULL;

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

    wchar_t ipstringbuffer[46];

    // Validate the parameters
    if (argc != 3) {
        wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
        wprintf(L"       provides protocol-independent translation\n");
        wprintf(L"       from a 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 GetAddrInfoW() function
    memset(&hints, 0, sizeof (hints));
    hints.ai_family = AF_UNSPEC;
    hints.ai_socktype = SOCK_STREAM;
    hints.ai_protocol = IPPROTO_TCP;

    wprintf(L"Calling GetAddrInfoEx with following parameters:\n");
    wprintf(L"\tName = %ws\n", argv[1]);
    wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);

//--------------------------------
// Call GetAddrInfoEx(). If the call succeeds,
// the aiList variable will hold a linked list
// of ADDRINFOEX structures containing response
// information about the host
    dwRetval = GetAddrInfoEx(argv[1], argv[2],
                             dwNamespace, lpNspid, &hints, &result,
                             NULL, NULL, NULL, NULL);

    if (dwRetval != 0) {
        wprintf(L"GetAddrInfoEx failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }
    wprintf(L"GetAddrInfoEx returned success\n");

    // Retrieve each address and print out the hex bytes
    for (ptr = result; ptr != NULL; ptr = ptr->ai_next) {

        wprintf(L"GetAddrInfoEx 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");
            // the InetNtop function is available on Windows Vista and later
            sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
            wprintf(L"\tIPv4 address %ws\n",
                    InetNtop(AF_INET, &sockaddr_ipv4->sin_addr, ipstringbuffer,
                             46));

            // We could also use the WSAAddressToString function
            // 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;
            wprintf(L"\tIPv6 address %ws\n",
                    InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr,
                             ipstringbuffer, 46));

            // We could also use WSAAddressToString which also returns the scope ID
            // 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);
    }

    FreeAddrInfoEx(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 funzione per ADDRINFOEX e GetAddrInfoEx.
 

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [solo app desktop]
Server minimo supportato Windows Server 2008 [solo app desktop]
Intestazione ws2def.h (includere Windows Server 2012, Windows 7 Windows Server 2008 R2)

Vedi anche

GetAddrInfoEx

addrinfo

addrinfoW