Struttura ADDRINFOW (ws2def.h)

La struttura addrinfoW viene utilizzata dalla funzione GetAddrInfoW per contenere le informazioni sull'indirizzo host.

Sintassi

typedef struct addrinfoW {
  int              ai_flags;
  int              ai_family;
  int              ai_socktype;
  int              ai_protocol;
  size_t           ai_addrlen;
  PWSTR            ai_canonname;
  struct sockaddr  *ai_addr;
  struct addrinfoW *ai_next;
} ADDRINFOW, *PADDRINFOW;

Members

ai_flags

Tipo: int

Flag che indicano le opzioni usate nella funzione GetAddrInfoW .

I valori supportati per il membro ai_flags sono definiti nel file di intestazione Winsock2.h e possono essere una combinazione delle opzioni elencate nella tabella seguente.

ai_family

Tipo: int

Famiglia di indirizzi. I valori possibili per la famiglia di indirizzi sono definiti nel file di intestazione 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.

Nella tabella seguente sono elencati i valori comuni per la famiglia di indirizzi, anche se sono possibili molti altri valori.

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.

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 protocollo e tipo di socket 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 quando vengono definiti nuovi tipi di socket, famiglie di indirizzi e protocolli.

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 il ai_protocol sono definiti nei file di intestazione Winsock2.h e 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 automaticamente incluso in Winsock2.h e non deve mai essere usato direttamente.

Se per ai_protocol viene specificato un valore pari a 0, 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.

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

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: PWSTR

Nome canonico per l'host.

ai_addr

Tipo: sockaddr struct*

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

ai_next

Tipo: struct addrinfoW*

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

Commenti

La struttura addrinfoW viene utilizzata dalla funzione Unicode GetAddrInfoW per contenere le informazioni sull'indirizzo host.

La struttura addrinfo è una versione ANSI di questa struttura usata dalla funzione getaddrinfo ANSI.

Le macro nel file di intestazione Ws2tcpip.h definiscono una struttura ADDRINFOT e un nome di funzione con maiuscole e minuscole getAddrInfo. La funzione GetAddrInfo deve essere chiamata con i parametri nodename e servname di un puntatore di tipo TCHAR e i parametri hint e res di un puntatore di tipo ADDRINFOT. Quando viene definito UNICODE o _UNICODE, ADDRINFOT viene definito alla struttura addrinfoW e GetAddrInfo è definito per GetAddrInfoW, la versione Unicode di questa funzione. Quando UNICODE o _UNICODE non è definito, ADDRINFOT viene definito per la struttura addrinfo e GetAddrInfo viene definito per getaddrinfo, la versione ANSI di questa funzione.

Al termine di una chiamata a GetAddrInfoW, viene restituito un elenco collegato di strutture ADDRINFOW nel parametro ppResult passato alla funzione GetAddrInfoW . 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 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 ADDRINFOW restituita punta a una struttura di indirizzi socket compilata, la cui lunghezza è specificata nel relativo membro ai_addrlen .

Esempio

Nell'esempio di codice seguente viene illustrato come usare la struttura addrinfoW .

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

    ADDRINFOW *result = NULL;
    ADDRINFOW *ptr = NULL;
    ADDRINFOW hints;

    DWORD dwRetval = 0;
    int i = 1;

    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 GetAddrInfoW with following parameters:\n");
    wprintf(L"\tName = %ws\n", argv[1]);
    wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);

//--------------------------------
// Call GetAddrInfoW(). If the call succeeds,
// the aiList variable will hold a linked list
// of addrinfo structures containing response
// information about the host
    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");
            // 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);
    }

    FreeAddrInfo(result);
    WSACleanup();

    return 0;
}

Requisiti

Vedi anche

GetAddrInfoEx

GetAddrInfoW

WSAEnumProtocols

addrinfo

addrinfoex

addrinfoex2

getaddrinfo

sockaddr