структура ADDRINFOEX4 (ws2def.h)
Структура 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 и могут быть комбинацией следующих параметров.
| Значение | Значение |
|---|---|
|
Адрес сокета будет использоваться при вызове функции bind . |
|
Каноническое имя возвращается в первом элементе ai_canonname . |
|
Параметр nodename , передаваемый в функцию GetAddrInfoEx , должен быть числовой строкой. |
|
Если этот бит задан, выполняется запрос на адреса IPv6 и IPv4 с AI_V4MAPPED.
Этот параметр поддерживается в Windows Vista и более поздних версиях. |
|
GetAddrInfoEx будет разрешаться, только если настроен глобальный адрес. Адрес замыкания на себя IPv6 и IPv4 не считается допустимым глобальным адресом.
Этот параметр поддерживается в Windows Vista и более поздних версиях. |
|
Если запрос GetAddrInfoEx для IPv6-адресов завершается сбоем, выполняется запрос службы имен для IPv4-адресов, и эти адреса преобразуются в формат IPv4-адресов.
Этот параметр поддерживается в Windows Vista и более поздних версиях. |
|
Адресная информация получена из результатов, не заслуживающих доверия.
Если этот параметр задан в параметре pHintsgetAddrInfoEx, поставщик пространства имен NS_EMAIL возвращает как заслуживающие доверия, так и неавторитетные результаты. Если этот параметр не задан, возвращаются только достоверные результаты. Этот параметр поддерживается только в Windows Vista и более поздних версиях для пространства имен NS_EMAIL . |
|
Сведения об адресе передаются из защищенного канала.
Если задан бит AI_SECURE , поставщик пространства имен NS_EMAIL вернет результаты, полученные с повышенной безопасностью, чтобы свести к минимуму возможные спуфинговы. Если этот параметр задан в параметре pHintsgetAddrInfoEx, поставщик пространства имен NS_EMAIL возвращает только результаты, полученные с повышенной безопасностью, чтобы свести к минимуму возможный спуфинг. Этот параметр поддерживается только в Windows Vista и более поздних версиях для пространства имен NS_EMAIL . |
|
Сведения об адресе относятся к предпочтительному имени публикации с определенным пространством имен.
Если этот параметр задан в параметре pHintsgetAddrInfoEx, в параметре pName не должно быть указано имя, а поставщик пространства имен NS_EMAIL вернет предпочтительные имена для публикации. Этот параметр поддерживается только в Windows Vista и более поздних версиях для пространства имен NS_EMAIL . |
|
Полное доменное имя возвращается в первом элементе ai_fqdn .
Если этот параметр задан в параметре pHintsgetAddrInfoEx и в параметре pName указано неструктурированное имя (одна метка), возвращается полное доменное имя, в которое в конечном итоге разрешается имя. Этот параметр поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях. |
|
Указание поставщику пространства имен о том, что запрашиваемое имя узла используется в сценарии общей папки. Поставщик пространства имен может игнорировать это указание.
Этот параметр поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях. |
|
Отключите автоматическое кодирование международного доменного имени с помощью Punycode в функциях разрешения имен, вызываемых функцией GetAddrInfoEx .
Этот параметр поддерживается в Windows 8, Windows Server 2012 и более поздних версиях. |
|
Указывает, что текущий объект расширен: addrinfoex2 или более поздней версии.
Этот параметр поддерживается в Windows 8.1, Windows Server 2012 R2 и более поздних версиях. |
|
Дескриптор разрешения возвращается в элементе 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), поэтому можно использовать любой из констант.
В таблице ниже перечислены распространенные значения для семейства адресов, хотя возможны и многие другие значения.
ai_socktype
Тип сокета. Возможные значения для типа сокета определяются в включаемом файле Winsock2.h .
В следующей таблице перечислены возможные значения типа сокета, поддерживаемого для сокетов Windows 2.
| Значение | Значение |
|---|---|
|
Предоставляет виртуационные, надежные двусторонние потоки байтов на основе соединений с механизмом передачи данных OOB. Использует протокол TCP для семейства адресов Интернета (AF_INET или AF_INET6). Если элемент ai_familyявляется AF_IRDA, то единственным поддерживаемым типом сокета является SOCK_STREAM . |
|
Поддерживает датаграммы, которые являются ненадежными буферами фиксированной (обычно небольшой) максимальной длины без подключения. Использует протокол UDP для семейства адресов Интернета (AF_INET или AF_INET6). |
|
Предоставляет необработанный сокет, позволяющий приложению управлять следующим заголовком протокола верхнего уровня. Чтобы управлять заголовком IPv4, для сокета необходимо задать параметр сокета IP_HDRINCL . Чтобы управлять заголовком IPv6, для сокета необходимо задать параметр сокета IPV6_HDRINCL . |
|
Предоставляет надежную датаграмму сообщений. Примером этого типа является реализация протокола прагматической общей многоадресной рассылки (PGM) в Windows, которую часто называют надежным многоадресным программированием. |
|
Предоставляет пакет псевдопотока на основе датаграмм. |
В 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 , хотя возможны и многие другие значения.
Если элемент 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 поддерживается в Windows 10 и Windows Server 2016
Структура 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 |