Функция GetAddrInfoW (ws2tcpip.h)

Статья
08/28/2023

Функция GetAddrInfoW обеспечивает независимое от протокола преобразование имени узла Юникода в адрес.

Синтаксис

INT WSAAPI GetAddrInfoW(
  [in, optional] PCWSTR          pNodeName,
  [in, optional] PCWSTR          pServiceName,
  [in, optional] const ADDRINFOW *pHints,
  [out]          PADDRINFOW      *ppResult
);

Параметры

[in, optional] pNodeName

Указатель на строку Юникода с завершением NULL, содержащую имя узла (узла) или числовую строку адреса узла. Для интернет-протокола строка числового адреса узла представляет собой IPv4-адрес с точками или шестнадцатеричный адрес IPv6.

[in, optional] pServiceName

Указатель на строку Юникода, завершающуюся значением NULL, которая содержит либо имя службы, либо номер порта, представленный в виде строки.

Имя службы — это строковый псевдоним для номера порта. Например, "http" — это псевдоним порта 80, определенный целевой группы по интернету (IETF) в качестве порта по умолчанию, используемого веб-серверами для протокола HTTP. Возможные значения параметра pServiceName , если номер порта не указан, перечислены в следующем файле:

%WINDIR%\system32\drivers\etc\services

[in, optional] pHints

Указатель на структуру addrinfoW , которая предоставляет подсказки о типе сокета, который поддерживает вызывающий объект.

Элементы ai_addrlen, ai_canonname, ai_addr и ai_next структуры addrinfoW , на которые указывает параметр pHints , должны иметь значение null или NULL. В противном случае функция GetAddrInfoEx завершится сбоем с WSANO_RECOVERY.

Дополнительные сведения см. в разделе Примечания.

[out] ppResult

Указатель на связанный список из одной или нескольких структур addrinfoW , содержащий сведения об ответе об узле.

Возвращаемое значение

При успешном выполнении возвращается ноль. Ошибка возвращает ненулевой код ошибки Сокеты Windows, как показано в коде ошибок сокетов Windows.

Большинство ненулевых кодов ошибок, возвращаемых функцией GetAddrInfoW , сопоставляются с набором ошибок, описанным в рекомендациях Целевой группы по разработке интернета (IETF). В следующей таблице перечислены эти коды ошибок и их эквиваленты WSA. Рекомендуется использовать коды ошибок WSA, так как они предоставляют знакомые и исчерпывающие сведения об ошибках для программистов Winsock.

Значение ошибки	Эквивалент WSA	Описание
EAI_AGAIN	WSATRY_AGAIN	Произошла временная ошибка разрешения имен.
EAI_BADFLAGS	WSAEINVAL	Для элемента ai_flags параметра pHints указано недопустимое значение.
EAI_FAIL	WSANO_RECOVERY	Произошел неустранимый сбой при разрешении имен.
EAI_FAMILY	WSAEAFNOSUPPORT	Элемент ai_family параметра pHints не поддерживается.
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	Произошел сбой выделения памяти.
EAI_NONAME	WSAHOST_NOT_FOUND	Имя не разрешается для указанных параметров или параметры pNodeName и pServiceName не указаны.
EAI_SERVICE	WSATYPE_NOT_FOUND	Параметр pServiceName не поддерживается для указанного элемента ai_socktype параметра pHints .
EAI_SOCKTYPE	WSAESOCKTNOSUPPORT	Элемент ai_socktype параметра pHints не поддерживается.

Используйте функцию gai_strerror для вывода сообщений об ошибках на основе кодов EAI_*, возвращаемых функцией GetAddrInfoW . Функция gai_strerror предоставляется для соответствия рекомендациям IETF, но не является потокобезопасной. Поэтому рекомендуется использовать традиционную функцию Windows Sockets, например WSAGetLastError.

Код ошибки	Значение
WSA_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения операции.
WSAEAFNOSUPPORT	Использовался адрес, несовместимый с запрошенным протоколом. Эта ошибка возвращается, если элемент ai_family структуры addrinfoW , на который указывает параметр hints , не поддерживается.
WSAEINVAL	Указан недопустимый аргумент. Эта ошибка возвращается, если для элемента ai_flags структуры addrinfoW , на которую указывает параметр hints , было указано недопустимое значение.
WSAESOCKTNOSUPPORT	Указанный тип сокета не поддерживается в данном семействе адресов. Эта ошибка возвращается, если элемент ai_socktype структуры addrinfoW , на который указывает параметр hints , не поддерживается.
WSAHOST_NOT_FOUND	Такой узел не существует. Эта ошибка возвращается, если имя не разрешается для предоставленных параметров или параметры pNodename и pServicename не указаны.
WSANO_DATA	Запрошенное имя является допустимым, но данные запрошенного типа не найдены.
WSANO_RECOVERY	При просмотре базы данных произошла неустранимая ошибка. Эта ошибка возвращается, если произошла неустранимая ошибка при разрешении имен.
WSANOTINITIALISED	Перед использованием этой функции должен быть выполнен успешный вызов WSAStartup .
WSATRY_AGAIN	Обычно это временная ошибка при разрешении имени узла, и она означает, что локальный сервер не получил ответа от заслуживающего доверия сервера. Эта ошибка возвращается при временном сбое разрешения имен.
WSATYPE_NOT_FOUND	Указанный класс не найден. Параметр pServiceName не поддерживается для указанного элемента ai_socktype структуры addrinfoW , на которую указывает параметр hints .

Функция GetAddrInfoW возвращает результаты для пространства имен NS_DNS . Функция GetAddrInfoW объединяет все ответы, если несколько поставщиков пространств имен возвращают сведения. Для использования с протоколами IPv6 и IPv4 разрешение имен может выполняться системой доменных имен (DNS), локальным файлом узлов или другими механизмами именования для пространства имен NS_DNS .

Макросы в файле заголовка Winsock определяют имя функции GetAddrInfo в смешанном регистре и структуру ADDRINFOT . Эта функция GetAddrInfo должна вызываться с параметрами pNodeName и pServiceName указателя типа TCHAR и параметрами pHints и ppResult указателя типа ADDRINFOT. При определении ЮНИКОДа или _UNICODE GetAddrInfo определяется как GetAddrInfoW, версия функции в Юникоде, а ADDRINFOT — для структуры addrinfoW . Если юникод или _UNICODE не определены, GetAddrInfo определяется как getaddrinfo, версия ANSI функции, а ADDRINFOT — для структуры addrinfo .

Один или оба параметра pNodeName или pServiceName должны указывать на строку Юникода, завершаемую null; как правило, предоставляются оба варианта.

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

Если параметр pNodeName указывает на имя компьютера, возвращаются все постоянные адреса компьютера, которые можно использовать в качестве исходного адреса. В Windows Vista и более поздних версиях эти адреса будут включать все одноадресные IP-адреса, возвращаемые функциями GetUnicastIpAddressTable или GetUnicastIpAddressEntry , в которых член SkipAsSource имеет значение false в структуре MIB_UNICASTIPADDRESS_ROW .

Если параметр pNodeName указывает на строку, равную localhost, возвращаются все адреса замыкания на себя на локальном компьютере.

Если параметр pNodeName содержит пустую строку, возвращаются все зарегистрированные адреса на локальном компьютере.

В Windows Server 2003 и более поздних версиях, если параметр pNodeName указывает на строку, равную ".. localmachine", возвращаются все зарегистрированные адреса на локальном компьютере.

Если параметр pNodeName ссылается на имя виртуального сервера кластера, возвращаются только адреса виртуальных серверов. В Windows Vista и более поздних версиях эти адреса будут включать все одноадресные IP-адреса, возвращаемые функциями GetUnicastIpAddressTable или GetUnicastIpAddressEntry , в которых член SkipAsSource имеет значение true в структуре MIB_UNICASTIPADDRESS_ROW . Дополнительные сведения о кластеризация см. в разделе Кластеризация Windows.

В Windows 7 с пакетом обновления 1 (SP1) и Windows Server 2008 R2 с пакетом обновления 1 (SP1) добавлена поддержка Netsh.exe для установки атрибута SkipAsSource для IP-адреса. Это также изменяет поведение таким образом, что если член SkipAsSource в структуре MIB_UNICASTIPADDRESS_ROW имеет значение false, IP-адрес будет зарегистрирован в DNS. Если для элемента SkipAsSource задано значение true, IP-адрес не регистрируется в DNS.

Доступно исправление для Windows 7 и Windows Server 2008 R2, которое добавляет поддержку Netsh.exe для задания атрибута SkipAsSource для IP-адреса. Это исправление также изменяет поведение таким образом, что если член SkipAsSource в структуре MIB_UNICASTIPADDRESS_ROW имеет значение false, IP-адрес будет зарегистрирован в DNS. Если для элемента SkipAsSource задано значение true, IP-адрес не регистрируется в DNS. Дополнительные сведения см. в статье База знаний (KB) 2386184.

Аналогичное исправление также доступно для Windows Vista с пакетом обновления 2 (SP2) и Windows Server 2008 с пакетом обновления 2 (SP2), которое добавляет поддержку Netsh.exe для задания атрибута SkipAsSource в IP-адресе. Это исправление также изменяет поведение таким образом, что если член SkipAsSource в структуре MIB_UNICASTIPADDRESS_ROW имеет значение false, IP-адрес будет зарегистрирован в DNS. Если для элемента SkipAsSource задано значение true, IP-адрес не регистрируется в DNS.

Вызывающие функции GetAddrInfoW могут предоставлять подсказки о поддерживаемом типе сокета с помощью структуры addrinfoW , на которую указывает параметр pHints . При использовании параметра pHints к связанной структуре addrinfoW применяются следующие правила:

Значение AF_UNSPEC для ai_family указывает, что вызывающий объект принимает только семейства AF_INET и AF_INET6 адресов. Обратите внимание, что AF_UNSPEC и PF_UNSPEC одинаковы.
Значение, равное нулю для ai_socktype , указывает, что вызывающий объект принимает любой тип сокета.
Значение, равное нулю для ai_protocol , указывает, что вызывающий объект примет любой протокол.
Элемент ai_addrlen должен иметь нулевое значение.
Элемент ai_canonname должен иметь значение NULL.
Элемент ai_addr должен иметь значение NULL.
Элемент ai_next должен иметь значение NULL.

Другие значения в структуре addrinfoW , предоставленной в параметре pHints, указывают на конкретные требования. Например, если вызывающий объект обрабатывает только IPv4 и не обрабатывает IPv6, для элемента ai_family должно быть задано значение AF_INET. В другом примере, если вызывающий объект обрабатывает только TCP и не обрабатывает UDP, элемент ai_socktype должен иметь значение SOCK_STREAM.

Если параметр pHints является указателем NULL , функция GetAddrInfoW обрабатывает его так, как если бы структура addrinfoW в pHints была инициализирована с ai_family элементом , для AF_UNSPEC а для всех остальных элементов задано значение 0.

В Windows Vista и более поздних версиях при вызове GetAddrInfoW из службы, если операция является результатом вызова службы пользовательским процессом, служба должна олицетворять пользователя. Это необходимо, чтобы обеспечить надлежащее применение безопасности.

Функцию GetAddrInfoW можно использовать для преобразования текстового строкового представления IP-адреса в структуру addrinfoW , содержащую структуру sockaddr для IP-адреса и других сведений. Для использования таким образом строка, на которую указывает параметр pNodeName , должна содержать текстовое представление IP-адреса, а структура addrinfoW , на которую указывает параметр pHints , должна иметь флаг AI_NUMERICHOST , установленный в элементе ai_flags . Строка, на которую указывает параметр pNodeName , может содержать текстовое представление адреса IPv4 или IPv6. Текстовый IP-адрес преобразуется в структуру addrinfoW , на которую указывает параметр ppResult . Возвращаемая структура addrinfoW содержит структуру sockaddr для IP-адреса, а также дополнительные сведения об IP-адресе. Чтобы этот метод работал со строкой адреса IPv6 в Windows Server 2003 и Windows XP, на локальном компьютере должен быть установлен протокол IPv6. В противном случае возвращается ошибка WSAHOST_NOT_FOUND .

Освобождение сведений об адресе от динамического выделения

Вся информация, возвращаемая функцией GetAddrInfoW , на которую указывает параметр ppResult , выделяется динамически, включая все структуры addrinfoW , структуры адресов сокетов и канонические строки имен узлов, на которые указывают структуры addrinfoW . Память, выделенная в результате успешного вызова этой функции, должна быть освобождена с последующим вызовом FreeAddrInfoW.

Пример кода

В следующем примере кода показано, как использовать функцию GetAddrInfoW .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

// set APPVER=5.02 for WinXP SP2 and later

int __cdecl wmain(int argc, wchar_t **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;
    INT iRetval;

    DWORD dwRetval;

    int i = 1;
    
    ADDRINFOW *result = NULL;
    ADDRINFOW *ptr = NULL;
    ADDRINFOW hints;

//    struct sockaddr_in6 *sockaddr_ipv6;
    LPSOCKADDR sockaddr_ip;

    wchar_t ipstringbuffer[46];
    DWORD ipbufferlength = 46;

    // Validate the parameters
    if (argc != 3) {
        wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
        wprintf(L"getaddrinfow provides protocol-independent translation\n");
        wprintf(L"   from an Unicode 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 getaddrinfo() function
    ZeroMemory( &hints, 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"\tnodename = %ws\n", argv[1]);
    wprintf(L"\tservname (or port) = %ws\n\n", argv[2]);
    

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

    FreeAddrInfoW(result);
    WSACleanup();

    return 0;
}

Примечание Убедитесь, что среда разработки предназначена для последней версии Ws2tcpip.h , которая включает определения структуры и функций для addrinfoW и GetAddrInfoW соответственно.

Международные доменные имена

Имена узлов в Интернете обычно состоят из очень ограниченного набора символов:

буквы верхнего и нижнего регистра английского алфавита в кодировке ASCII;
цифры от 0 до 9;
Символы дефиса ASCII.

С ростом интернета растет потребность в определении имен узлов Интернета для других языков, не представленных кодировкой ASCII. Идентификаторы, которые упрощают эту потребность и позволяют представлять символы, отличные от ASCII (Юникод), в виде специальных строк символов ASCII, называются международными доменными именами (IDN). Механизм под названием Интернационализация доменных имен в приложениях (IDNA) используется для стандартной обработки IDN. Спецификации idn и IDNA задокументированы в документах RFC 3490, RTF 5890 и RFC 6365 , опубликованных Целевой группой по проектированию Интернета (IETF).

В Windows 8 и Windows Server 2012 функция GetAddrInfoW обеспечивает поддержку синтаксического анализа международного доменного имени (IDN), применяемого к имени, переданного в параметре pNodeName . Winsock выполняет кодирование и преобразование Punycode/IDN. Это поведение можно отключить с помощью флага AI_DISABLE_IDN_ENCODING , описанного ниже.

В Windows 7 и Windows Server 2008 R2 или более ранних версиях функция GetAddrInfoW в настоящее время не поддерживает синтаксический анализ IDN, применяемый к имени, переданного в параметре pNodeName . Winsock не выполняет преобразование Punycode/IDN. Функция GetAddrInfoW не использует Punycode для преобразования idN в формате RFC 3490. Функция GetAddrInfoW при запросе DNS кодирует имя Юникода в формате UTF-8, формате, используемом DNS-серверами Майкрософт в корпоративной среде.

Некоторые функции в Windows Vista и более поздних версиях поддерживают преобразование меток Юникода в IDN в их эквиваленты ASCII. Итоговое представление каждой метки Юникода содержит только символы ASCII и начинается с префикса xn--, если метка Юникода содержит символы, отличные от ASCII. Причина заключается в поддержке существующих DNS-серверов в Интернете, так как некоторые средства и серверы DNS поддерживают только символы ASCII (см. RFC 3490).

Функция IdnToAscii использует Punycode для преобразования IDN в представление ASCII исходной строки Юникода с помощью стандартного алгоритма, определенного в RFC 3490. Функция IdnToUnicode преобразует форму ASCII idN в обычный синтаксис кодировки Юникод UTF-16. Дополнительные сведения и ссылки на соответствующие проекты стандартов см. в разделе Обработка международных доменных имен (IDN).

Функцию IdnToAscii можно использовать для преобразования имени IDN в форму ASCII. Чтобы передать эту форму ASCII в функцию GetAddrInfoW , можно использовать функцию MultiByteToWideChar для преобразования строки CHAR в строку WCHAR , которую затем можно передать в параметре pNodeName в функцию GetAddrInfoW .

Использование ai_flags в параметре hints

Флаги в ai_flags член необязательной структуры addrinfoW , предоставленной в параметре pHints, изменяют поведение функции.

Эти биты флагов определены в файле заголовка Ws2def.h в пакете средств разработки программного обеспечения Microsoft Windows (SDK) для Windows 7. Эти биты флагов определены в файле заголовка Ws2tcpip.h в windows SDK для Windows Server 2008 и Windows Vista. Эти биты флагов определены в файле заголовка Ws2tcpip.h пакета sdk для Windows Server 2003 и Windows XP.

Биты флагов могут быть комбинацией следующих:

Биты флагов	Описание
AI_PASSIVE	Установка флага AI_PASSIVE указывает, что вызывающий объект намерен использовать возвращенную структуру адресов сокета в вызове функции bind . Если флаг AI_PASSIVE установлен, а pNodeName является указателем NULL , для части IP-адреса структуры адресов сокета устанавливается значение INADDR_ANY для IPv4-адресов и IN6ADDR_ANY_INIT для IPv6-адресов. Если флаг AI_PASSIVE не задан, возвращаемая структура адресов сокета готова к вызову функции connect для протокола, ориентированного на подключение, или для вызова функций connect, sendto или send для протокола без подключения. Если параметр pNodeName в данном случае является указателем NULL , для части IP-адреса структуры адресов сокета устанавливается адрес замыкания на себя.
AI_CANONNAME	Если ни AI_CANONNAME , ни AI_NUMERICHOST не используются, функция GetAddrInfoW пытается разрешить. Если передается литерал строки , GetAddrInfoW пытается преобразовать строку, а если передается имя узла, функция GetAddrInfoW пытается разрешить имя в адрес или несколько адресов. Если задан бит AI_CANONNAME , параметр pNodeName не может иметь значение NULL. В противном случае функция GetAddrInfoEx завершится сбоем с WSANO_RECOVERY. Если задан бит AI_CANONNAME и функция GetAddrInfoW возвращает успешное выполнение, элемент ai_canonname в параметре ppResult указывает на строку, завершающуюся значением NULL, которая содержит каноническое имя указанного узла. Примечание Функция GetAddrInfoW может возвращать успешное выполнение, если установлен флаг AI_CANONNAME , но элемент ai_canonname в связанной структуре addrinfoW имеет значение NULL. Поэтому рекомендуемое использование флага AI_CANONNAME включает проверку того, имеет ли элемент ai_canonname в связанной структуре addrinfoWзначение NULL.
AI_NUMERICHOST	Если задан бит AI_NUMERICHOST , параметр pNodeName должен содержать строку адреса узла, отличной от NULL , в противном случае возвращается ошибка EAI_NONAME . Этот флаг предотвращает вызов службы разрешения имен.
AI_NUMERICSERV	Если задан бит AI_NUMERICSERV , параметр pServiceName должен содержать номер порта, отличный от NULL , в противном случае возвращается ошибка EAI_NONAME . Этот флаг предотвращает вызов службы разрешения имен. Флаг AI_NUMERICSERV определен в Windows SDK для Windows Vista и более поздних версий. Флаг AI_NUMERICSERV не поддерживается поставщиками Майкрософт.
AI_ALL	Если задан бит AI_ALL , выполняется запрос на IPv6-адреса и IPv4-адреса с AI_V4MAPPED. Флаг AI_ALL определен в windows SDK для Windows Vista и более поздних версий. Флаг AI_ALL поддерживается в Windows Vista и более поздних версиях.
AI_ADDRCONFIG	Если задан бит AI_ADDRCONFIG , Метод GetAddrInfoW будет разрешаться только в том случае, если настроен глобальный адрес. Если указан AI_ADDRCONFIG флаг, IPv4-адреса должны возвращаться только в том случае, если В локальной системе настроен IPv4-адрес, а адреса IPv6 должны возвращаться только в том случае, если В локальной системе настроен IPv6-адрес. Адрес замыкания на себя IPv4 или IPv6 не считается допустимым глобальным адресом. Флаг AI_ADDRCONFIG определен в windows SDK для Windows Vista и более поздних версий. Флаг AI_ADDRCONFIG поддерживается в Windows Vista и более поздних версиях.
AI_V4MAPPED	Если задан бит AI_V4MAPPED и запрос IPv6-адресов завершается сбоем, выполняется запрос службы имен для IPv4-адресов и эти адреса преобразуются в формат IPv6-адресов. Флаг AI_V4MAPPED определен в windows SDK для Windows Vista и более поздних версий. Флаг AI_V4MAPPED поддерживается в Windows Vista и более поздних версиях.
AI_NON_AUTHORITATIVE	Если задан бит AI_NON_AUTHORITATIVE , поставщик пространства имен NS_EMAIL возвращает как заслуживающие доверия, так и не заслуживающие доверия результаты. Если бит AI_NON_AUTHORITATIVE не задан, поставщик пространства имен NS_EMAIL возвращает только достоверные результаты. Флаг AI_NON_AUTHORITATIVE определен в windows SDK для Windows Vista и более поздних версий. Флаг AI_NON_AUTHORITATIVE поддерживается в Windows Vista и более поздних версиях и применяется только к пространству имен NS_EMAIL .
AI_SECURE	Если задан бит AI_SECURE , поставщик пространства имен NS_EMAIL вернет результаты, полученные с повышенной безопасностью, чтобы свести к минимуму возможный спуфингов. Флаг AI_SECURE определен в windows SDK для Windows Vista и более поздних версий. Флаг AI_SECURE поддерживается в Windows Vista и более поздних версиях и применяется только к пространству имен NS_EMAIL .
AI_RETURN_PREFERRED_NAMES	Если AI_RETURN_PREFERRED_NAMES задано, то в параметре pNodeName не должно быть указано имя. Поставщик пространства имен NS_EMAIL вернет предпочтительные имена для публикации. Флаг AI_RETURN_PREFERRED_NAMES определен в windows SDK для Windows Vista и более поздних версий. Флаг AI_RETURN_PREFERRED_NAMES поддерживается в Windows Vista и более поздних версиях и применяется только к пространству имен NS_EMAIL .
AI_FQDN	Если задано AI_FQDN и указано неструктурированное имя (одна метка), GetAddrInfoW вернет полное доменное имя, в которое в конечном итоге будет разрешено имя. Полное доменное имя возвращается в элементе ai_canonname в связанной структуре addrinfoW . Это отличается от AI_CANONNAME битового флага, возвращающего каноническое имя, зарегистрированное в DNS, которое может отличаться от полного доменного имени, в которое разрешается неструктурированное имя. Можно задать только один из AI_FQDN и AI_CANONNAME битов. Функция GetAddrInfoW завершится ошибкой, если оба флага присутствуют с EAI_BADFLAGS. Если задан бит AI_FQDN , параметр pNodeName не может иметь значение NULL. В противном случае функция GetAddrInfoEx завершится сбоем с WSANO_RECOVERY. Windows 7: Флаг AI_FQDN определен в windows SDK для Windows 7 и более поздних версий. Флаг AI_FQDN поддерживается в Windows 7 и более поздних версиях.
AI_FILESERVER	Если задано AI_FILESERVER , это указание поставщику пространства имен на то, что запрашиваемое имя узла используется в сценарии общей папки. Поставщик пространства имен может игнорировать это указание. Windows 7: Флаг AI_FILESERVER определен в windows SDK для Windows 7 и более поздних версий. Флаг AI_FILESERVER поддерживается в Windows 7 и более поздних версиях.
AI_DISABLE_IDN_ENCODING	Если задано AI_DISABLE_IDN_ENCODING , это отключает автоматическую кодировку международного доменного имени с помощью Punycode в функциях разрешения имен, вызываемых функцией GetAddrInfoW . Windows 8: Флаг AI_DISABLE_IDN_ENCODING определен в windows SDK для Windows 8 и более поздних версий. Флаг AI_DISABLE_IDN_ENCODING поддерживается в Windows 8 и более поздних версиях.

Windows 8.1 и Windows Server 2012 R2: эта функция поддерживается для приложений Магазина Windows на Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Примечание

Заголовок ws2tcpip.h определяет GetAddrInfo в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows 8.1, Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	ws2tcpip.h
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll