Структура ADDRINFOEXW (ws2def.h)

Структура addrinfoex используется функцией GetAddrInfoEx для хранения сведений об адресе узла.

Синтаксис

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;

Члены

ai_flags

Тип: int

Флаги, указывающие параметры, используемые в функции GetAddrInfoEx .

Поддерживаемые значения для элемента ai_flags определяются в файле Winsock2.h include и могут быть комбинацией следующих параметров.

ai_family

Тип: int

Семейство адресов. Возможные значения для семейства адресов определяются в включаемом файле Winsock2.h .

На Windows SDK, выпущенном для Windows Vista и более поздних версий, организация файлов заголовков изменилась, а возможные значения для семейства адресов определяются в файле заголовка Ws2def.h. Обратите внимание, что файл заголовка Ws2def.h автоматически включается в Winsock2.h и никогда не должен использоваться напрямую.

В настоящее время поддерживаются значения AF_INET или AF_INET6, которые являются форматами семейства адресов Интернета для IPv4 и IPv6. Другие параметры семейства адресов (например, AF_NETBIOS для использования с NetBIOS) поддерживаются, если установлен поставщик служб Windows Sockets для семейства адресов. Обратите внимание, что значения для семейства адресов AF_ и констант семейства протоколов PF_ идентичны (например, AF_UNSPEC и PF_UNSPEC), поэтому можно использовать любой из констант.

В таблице ниже перечислены распространенные значения для семейства адресов, хотя возможны и многие другие значения.

ai_socktype

Тип: int

Тип сокета. Возможные значения для типа сокета определяются во включаемом файле Winsock2.h .

В следующей таблице перечислены возможные значения для типа сокета, поддерживаемого для Windows Sockets 2:

В Windows Sockets 2 появились новые типы сокетов. Приложение может динамически обнаруживать атрибуты каждого доступного транспортного протокола с помощью функции WSAEnumProtocols . Поэтому приложение может определить возможный тип сокета и параметры протокола для семейства адресов и использовать эти сведения при указании этого параметра. Определения типов сокетов в файлах заголовков Winsock2.h и Ws2def.h будут периодически обновляться по мере определения новых типов сокетов, семейств адресов и протоколов.

В Windows Sockets 1.1 единственными возможными типами сокетов являются SOCK_DATAGRAM и SOCK_STREAM.

ai_protocol

Тип: int

Тип протокола. Возможные параметры относятся к указанному семейству адресов и типу сокета. Возможные значения для ai_protocol определяются в файлах заголовков Winsock2.h и Wsrm.h .

В Windows SDK, выпущенном для Windows Vista и более поздних версий, организация файлов заголовков изменилась, и этот элемент может быть одним из значений из типа перечисления IPPROTO, определенного в файле заголовка Ws2def.h. Обратите внимание, что файл заголовка Ws2def.h автоматически включается в Winsock2.h и никогда не должен использоваться напрямую.

Если для ai_protocol задано значение 0, вызывающий объект не хочет указывать протокол, и поставщик услуг выберет ai_protocol для использования. Для протоколов, отличных от IPv4 и IPv6, задайте для ai_protocol нулевое значение.

В следующей таблице перечислены общие значения для элемента ai_protocol , хотя возможны и многие другие значения.

Если элемент ai_familyявляется AF_IRDA, то ai_protocol должен иметь значение 0.

ai_addrlen

Тип: size_t

Длина (в байтах) буфера, на который указывает элемент ai_addr .

ai_canonname

Тип: PCTSTR

Каноническое имя узла.

ai_addr

Тип: struct sockaddr*

Указатель на структуру sockaddr . Элемент ai_addr в каждой возвращаемой структуре addrinfoex указывает на заполненную структуру адресов сокета. Длина в байтах каждой возвращаемой структуры addrinfoex указывается в элементе ai_addrlen .

ai_blob

Тип: void*

Указатель на данные, используемые для возврата сведений о пространстве имен конкретного поставщика, связанных с именем за пределами списка адресов. Длина буфера, на который указывает ai_blob , в байтах должна быть указана в элементе ai_bloblen .

ai_bloblen

Тип: size_t

Длина элемента ai_blob в байтах.

ai_provider

Тип: LPGUID

Указатель на GUID определенного поставщика пространства имен.

ai_next

Тип: struct addrinfoex*

Указатель на следующую структуру в связанном списке. Для этого параметра задано значение NULL в последней структуре addrinfoex связанного списка.

Комментарии

Структура addrinfoex используется функцией GetAddrInfoEx для хранения сведений об адресе узла. Структура addrinfoex — это расширенная версия структур addrinfo и addrinfoW . Дополнительные элементы структуры предназначены для данных BLOB-объектов и GUID для поставщика пространства имен. Данные большого двоичного объекта используются для возврата дополнительных сведений о пространстве имен поставщика, связанных с именем. Формат данных в элементе ai_blob зависит от конкретного поставщика пространства имен. В настоящее время данные больших двоичных объектов используются поставщиком пространства имен NS_EMAIL для предоставления дополнительных сведений.

Структура addrinfoex — это расширенная версия структуры addrinfo и addrinfoW , используемой с функцией GetAddrInfoEx . Функция GetAddrInfoEx позволяет указать поставщика пространства имен для разрешения запроса. Для использования с протоколами IPv6 и IPv4 разрешение имен может осуществляться системой доменных имен (DNS), локальным файлом hosts , поставщиком электронной почты ( пространство имен NS_EMAIL ) или другими механизмами именования.

Если определен ЮНИКОД или _UNICODE, addrinfoex определяется как addrinfoexW, версия Юникода этой структуры. Строковые параметры определяются для типа данных PWSTR и используется структура addrinfoexW .

Если юникод или _UNICODE не определены, addrinfoex определяется как addrinfoexA, версия ANSI этой структуры. Строковые параметры относятся к типу данных PCSTR и используется структура addrinfoexA .

После успешного вызова GetAddrInfoEx связанный список структур addrinfoex возвращается в параметре ppResult , передаваемом в функцию GetAddrInfoEx . Список можно обработать, следуя указателю, указанному в элементе ai_next каждой возвращаемой структуры addrinfoex , пока не будет обнаружен указатель NULL . В каждой возвращаемой структуре addrinfoexчлены ai_family, ai_socktype и ai_protocol соответствуют соответствующим аргументам в вызове функции сокета или WSASocket . Кроме того, элемент ai_addr в каждой возвращаемой структуре addrinfoex указывает на заполненную структуру адресов сокета, длина которой указана в его ai_addrlen элементе.

Примеры

В следующем примере показано использование структуры 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;
}

Требования

См. также раздел

GetAddrInfoEx

addrinfo

addrinfoW