структура ADDRINFOEX4 (ws2def.h)

Статья
03/15/2023

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

Синтаксис

typedef struct addrinfoex4 {
  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;
  GUID               *ai_provider;
  struct addrinfoex4 *ai_next;
  int                ai_version;
  PWSTR              ai_fqdn;
  int                ai_interfaceindex;
  HANDLE             ai_resolutionhandle;
} ADDRINFOEX4, *PADDRINFOEX4, *LPADDRINFOEX4;

Члены

ai_flags

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

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

Значение	Значение
AI_PASSIVE 0x01	Адрес сокета будет использоваться при вызове функции bind .
AI_CANONNAME 0x02	Каноническое имя возвращается в первом элементе ai_canonname .
AI_NUMERICHOST 0x04	Параметр nodename , передаваемый в функцию GetAddrInfoEx , должен быть числовой строкой.
AI_ALL 0x0100	Если этот бит задан, выполняется запрос на адреса IPv6 и IPv4 с AI_V4MAPPED. Этот параметр поддерживается в Windows Vista и более поздних версиях.
AI_ADDRCONFIG 0x0400	GetAddrInfoEx будет разрешаться, только если настроен глобальный адрес. Адрес замыкания на себя IPv6 и IPv4 не считается допустимым глобальным адресом. Этот параметр поддерживается в Windows Vista и более поздних версиях.
AI_V4MAPPED 0x0800	Если запрос GetAddrInfoEx для IPv6-адресов завершается сбоем, выполняется запрос службы имен для IPv4-адресов, и эти адреса преобразуются в формат IPv4-адресов. Этот параметр поддерживается в Windows Vista и более поздних версиях.
AI_NON_AUTHORITATIVE 0x04000	Адресная информация получена из результатов, не заслуживающих доверия. Если этот параметр задан в параметре pHintsgetAddrInfoEx, поставщик пространства имен NS_EMAIL возвращает как заслуживающие доверия, так и неавторитетные результаты. Если этот параметр не задан, возвращаются только достоверные результаты. Этот параметр поддерживается только в Windows Vista и более поздних версиях для пространства имен NS_EMAIL .
AI_SECURE 0x08000	Сведения об адресе передаются из защищенного канала. Если задан бит AI_SECURE , поставщик пространства имен NS_EMAIL вернет результаты, полученные с повышенной безопасностью, чтобы свести к минимуму возможные спуфинговы. Если этот параметр задан в параметре pHintsgetAddrInfoEx, поставщик пространства имен NS_EMAIL возвращает только результаты, полученные с повышенной безопасностью, чтобы свести к минимуму возможный спуфинг. Этот параметр поддерживается только в Windows Vista и более поздних версиях для пространства имен NS_EMAIL .
AI_RETURN_PREFERRED_NAMES 0x010000	Сведения об адресе относятся к предпочтительному имени публикации с определенным пространством имен. Если этот параметр задан в параметре pHintsgetAddrInfoEx, в параметре pName не должно быть указано имя, а поставщик пространства имен NS_EMAIL вернет предпочтительные имена для публикации. Этот параметр поддерживается только в Windows Vista и более поздних версиях для пространства имен NS_EMAIL .
AI_FQDN 0x00020000	Полное доменное имя возвращается в первом элементе ai_fqdn . Если этот параметр задан в параметре pHintsgetAddrInfoEx и в параметре pName указано неструктурированное имя (одна метка), возвращается полное доменное имя, в которое в конечном итоге разрешается имя. Этот параметр поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях.
AI_FILESERVER 0x00040000	Указание поставщику пространства имен о том, что запрашиваемое имя узла используется в сценарии общей папки. Поставщик пространства имен может игнорировать это указание. Этот параметр поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях.
AI_DISABLE_IDN_ENCODING 0x00080000	Отключите автоматическое кодирование международного доменного имени с помощью Punycode в функциях разрешения имен, вызываемых функцией GetAddrInfoEx . Этот параметр поддерживается в Windows 8, Windows Server 2012 и более поздних версиях.
AI_EXTENDED 0x80000000	Указывает, что текущий объект расширен: addrinfoex2 или более поздней версии. Этот параметр поддерживается в Windows 8.1, Windows Server 2012 R2 и более поздних версиях.
AI_RESOLUTION_HANDLE 0x40000000	Дескриптор разрешения возвращается в элементе ai_resolutionhandle . Этот параметр поддерживается в Windows 10, Windows Server 2016 и более поздних версиях.

ai_family

Семейство адресов.

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

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

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

Значение	Значение
AF_UNSPEC 0	Семейство адресов не указано.
AF_INET 2	Семейство адресов IPv4.
AF_NETBIOS 17	Семейство адресов NetBIOS. Это семейство адресов поддерживается только в том случае, если установлен поставщик Сокетов Windows для NetBIOS.
AF_INET6 23	Семейство адресов IPv6.
AF_IRDA 26	Семейство адресов Ассоциации инфракрасных данных (IrDA). Это семейство адресов поддерживается только в том случае, если на компьютере установлен инфракрасный порт и драйвер.
AF_BTH 32	Семейство адресов Bluetooth. Это семейство адресов поддерживается только в том случае, если установлен адаптер Bluetooth.

ai_socktype

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

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

Значение	Значение
SOCK_STREAM 1	Предоставляет виртуационные, надежные двусторонние потоки байтов на основе соединений с механизмом передачи данных OOB. Использует протокол TCP для семейства адресов Интернета (AF_INET или AF_INET6). Если элемент ai_familyявляется AF_IRDA, то единственным поддерживаемым типом сокета является SOCK_STREAM .
SOCK_DGRAM 2	Поддерживает датаграммы, которые являются ненадежными буферами фиксированной (обычно небольшой) максимальной длины без подключения. Использует протокол UDP для семейства адресов Интернета (AF_INET или AF_INET6).
SOCK_RAW 3	Предоставляет необработанный сокет, позволяющий приложению управлять следующим заголовком протокола верхнего уровня. Чтобы управлять заголовком IPv4, для сокета необходимо задать параметр сокета IP_HDRINCL . Чтобы управлять заголовком IPv6, для сокета необходимо задать параметр сокета IPV6_HDRINCL .
SOCK_RDM 4	Предоставляет надежную датаграмму сообщений. Примером этого типа является реализация протокола прагматической общей многоадресной рассылки (PGM) в Windows, которую часто называют надежным многоадресным программированием.
SOCK_SEQPACKET 5	Предоставляет пакет псевдопотока на основе датаграмм.

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

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

ai_protocol

Тип протокола. Возможные варианты зависят от указанного семейства адресов и типа сокета. Возможные значения для 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 , хотя возможны и многие другие значения.

Значение	Значение
IPPROTO_TCP 6	Протокол TCP. Это возможное значение, если элемент ai_familyAF_INET или AF_INET6 , а элемент ai_socktypeSOCK_STREAM.
IPPROTO_UDP 17	Протокол UDP. Это возможное значение, если элемент ai_familyAF_INET или AF_INET6 , а параметр type — SOCK_DGRAM.
IPPROTO_RM 113	Протокол PGM для надежной многоадресной рассылки. Это возможное значение, если элемент ai_familyAF_INET , а элемент ai_socktype— SOCK_RDM. На Windows SDK, выпущенном для Windows Vista и более поздних версий, это значение также называется IPPROTO_PGM.

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

ai_addrlen

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

ai_canonname

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

ai_addr

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

ai_blob

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

ai_bloblen

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

ai_provider

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

ai_next

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

ai_version

Номер версии этой структуры. В настоящее время для этой версии структуры используется значение 4.

ai_fqdn

Полное доменное имя узла.

ai_interfaceindex

Индекс интерфейса, определенный IP_ADAPTER_ADDRESSES. Свойство IfIndex , возвращаемое в GetAdaptersAddresses.

ai_resolutionhandle

Дескриптор указывает на полное доменное имя узла.

Структура addrinfoex4 используется функцией GetAddrInfoEx для хранения сведений об адресе узла, когда AI_EXTENDED | AI_FQDN | AI_CANONNAME | AI_RESOLUTION_HANDLE битов заданы в элементе addrinfoex4.ai_flags передаваемых через GetAddrInfoEx.параметр hints .

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

Данные большого двоичного объекта в элементе tha ai_blob используются для возврата дополнительных сведений о пространстве имен поставщика, связанных с именем. Формат данных в элементе ai_blob зависит от конкретного поставщика пространства имен. В настоящее время данные больших двоичных объектов используются поставщиком пространства имен NS_EMAIL для предоставления дополнительных сведений.

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

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

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

Примеры

В следующем коде описывается вызов GetAddrInfoEx со структурой addrinfoex4 для получения дескриптора полного доменного имени. Затем в примере вызовите WSAIoctl со структурой ASSOCIATE_NAMERES_CONTEXT_INPUT .

// 
// Connect to a server using its IPv4 addresses 
// 

VOID 
ConnectServer( 
    PCWSTR server) 
{ 
    int iResult; 
    PADDRINFOEX4 pResult = NULL; 
    ADDRINFOEX3 hints = { 0 }; 
    PADDRINFOEX4 pCur = NULL; 
    WSADATA wsaData; 
    SOCKET connectSocket = INVALID_SOCKET; 
    ULONG bytesReturned = 0; 
    ASSOCIATE_NAMERES_CONTEXT_INPUT input = { 0 }; 
    SOCKADDR_IN clientService; 
    wchar_t ipstringbuffer[46]; 
    String string; 
    DWORD dwRetval; 
    //  
    //  Initialize Winsock 
    // 
    iResult = WSAStartup( 
        MAKEWORD(2, 2),  
        &wsaData); 
    if (iResult != 0) { 
        printf("WSAStartup failed: %d\n", iResult); 
        goto Exit; 
    } 

    //  
    // Create a SOCKET for connection 
    // 
    connectSocket = socket( 
        AF_UNSPEC,  
        SOCK_STREAM,  
        IPPROTO_TCP); 
    if (connectSocket == INVALID_SOCKET)  
    { 
        printf("socket failed: %d\n", WSAGetLastError()); 
        goto Exit; 
    } 

    // 
    // Do name resolution 
    // 

    hints.ai_family = AF_INET; 
    hints.ai_socktype = SOCK_STREAM; 
    hints.ai_flags = AI_EXTENDED | AI_FQDN | AI_CANONNAME | AI_RESOLUTION_HANDLE; 
    hints.ai_version = ADDRINFOEX_VERSION_4; 

    dwRetval = GetAddrInfoExW( 
        server, 
        NULL, 
        NS_DNS, 
        NULL, 
        (const ADDRINFOEXW*)&hints, 
        (PADDRINFOEXW*)&pResult, 
        NULL, 
        NULL, 
        NULL, NULL); 
    if (dwRetval != 0) { 
        printf("GetAddrInfoEx failed with error: %d\n", dwRetval); 
        goto Exit; 
    } 
    input.TransportSettingId.Guid = ASSOCIATE_NAMERES_CONTEXT; 
    input.Handle = pResult->ai_resolutionhandle; 

    // 
    // Associate socket with the handle 
    // 

    if (WSAIoctl( 
            connectSocket, 
            SIO_APPLY_TRANSPORT_SETTING, 
            (VOID *)&input, 
            sizeof(input), 
            NULL, 
            0, 
            &bytesReturned, 
            NULL, 
            NULL) == SOCKET_ERROR) 
    if (iResult != 0){ 
        printf("WSAIoctl failed: %d\n", WSAGetLastError()); 
        goto Exit; 
    }     

    // 
    // Connect to server 
    // 

    pCur = pResult; 
    while (pCur != NULL) 
    { 
        if (pCur->ai_addr->sa_family == AF_INET) 
        { 
            clientService = *(const sockaddr_in*)pCur->ai_addr; 
            clientService.sin_port = htons(80); 
            if (connect( 
                connectSocket, 
                (const SOCKADDR *)&clientService, 
                sizeof(clientService)) == SOCKET_ERROR) 
            { 
                printf("connect failed: %d\n", WSAGetLastError()); 
                goto Exit; 
            } 
        } 
        pCur = pCur->ai_next; 
    } 

Exit: 

    if (connectSocket != INVALID_SOCKET) 
    { 
        closesocket(connectSocket); 
    } 
    if (pResult) 
    { 
        FreeAddrInfoExW((ADDRINFOEXW*)pResult); 
    } 
    WSACleanup(); 
    return; 
}

Требования

Требование	Значение
Минимальная версия клиента	Windows 10 [только классические приложения]
Минимальная версия сервера	Windows Server 2016 [только классические приложения]
Верхняя часть	ws2def.h