ADDRINFOEXW 结构 （ws2def.h）

GetAddrInfoEx 函数使用 addrinfoex 结构来保存主机地址信息。

语法

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 包含文件中定义，并且可以是以下选项的组合。

ai_family

类型：int

地址系列。 地址系列的可能值在 Winsock2.h include 文件中定义。

在适用于 Windows Vista 及更高版本的 Windows SDK 上，头文件的组织已更改，地址系列的可能值在 Ws2def.h 头文件中定义。 请注意，Ws2def.h 头文件自动包含在 Winsock2.h中，不应直接使用。

当前支持的值是 AF_INET 或 AF_INET6，它们是 IPv4 和 IPv6 的 Internet 地址系列格式。 如果安装了地址系列的 Windows 套接字服务提供商，则支持地址系列的其他选项（例如，用于 NetBIOS 的AF_NETBIOS）。 请注意，AF_地址系列和PF_协议系列常量的值相同（例如，AF_UNSPEC 和 PF_UNSPEC），因此可以使用任一常量。

下表列出了地址系列的公共值，尽管可能有多个其他值。

ai_socktype

类型：int

套接字类型。 套接字类型的可能值在 Winsock2.h include 文件中定义。

下表列出了 Windows 套接字 2 支持的套接字类型的可能值：

在 Windows 套接字 2 中，引入了新的套接字类型。 应用程序可以通过 WSAEnumProtocols 函数动态发现每个可用传输协议的属性。 因此，应用程序可以确定地址系列可能的套接字类型和协议选项，并在指定此参数时使用此信息。 Winsock2.h 和 Ws2def.h 头文件中的套接字类型定义将定期更新，因为定义了新的套接字类型、地址系列和协议。

在 Windows 套接字 1.1 中，唯一可能的套接字类型是 SOCK_DATAGRAM 和 SOCK_STREAM。

ai_protocol

类型：int

协议类型。 可能的选项特定于指定的地址系列和套接字类型。 Winsock2.h 和 Wsrm.h 头文件中定义了 ai_protocol 的可能值。

在适用于 Windows Vista 及更高版本的 Windows SDK 上，头文件的组织已更改，此成员可以是 Ws2def.h 头文件中定义的 IPPROTO 枚举类型之一。 请注意，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

类型：结构 sockaddr*

指向 sockaddr 结构的指针。 每个返回 addrinfoex 结构中的 ai_addr 成员指向填充的套接字地址结构。 ai_addrlen 成员中指定了每个返回 addrinfoex 结构的长度（以字节为单位）。

ai_blob

类型：void*

指向用于返回与地址列表以外的名称关联的特定于提供程序的命名空间信息的数据的指针。 ai_blob 指向的缓冲区的长度（以字节为单位）必须在 ai_bloblen 成员中指定。

ai_bloblen

类型：size_t

ai_blob 成员的长度（以字节为单位）。

ai_provider

类型：LPGUID

指向特定命名空间提供程序 GUID 的指针。

ai_next

类型：结构 addrinfoex*

指向链接列表中的下一个结构的指针。 此参数设置为在链接列表的最后一 addrinfoex 结构中 NULL。

言论

GetAddrInfoEx 函数使用 addrinfoex 结构来保存主机地址信息。 addrinfoex 结构的 是 addrinfo 和 addrinfoW 结构的增强版本。 额外的结构成员用于 Blob 数据和命名空间提供程序的 GUID。 Blob 数据用于返回与名称关联的其他特定于提供程序的命名空间信息。 ai_blob 成员中的数据格式特定于特定的命名空间提供程序。 目前，NS_EMAIL 命名空间提供程序使用 blob 数据来提供其他信息。

addrinfoex 结构是 addrinfo 和 addrinfoW 结构的增强版本，用于 GetAddrInfoEx 函数。 GetAddrInfoEx 函数允许指定命名空间提供程序解析查询。 若要与 IPv6 和 IPv4 协议一起使用，名称解析可以由域名系统（DNS）、本地 主机 文件、电子邮件提供程序（NS_EMAIL 命名空间）或其他命名机制使用。

定义 UNICODE 或_UNICODE时，addrinfoex 定义为 addrinfoexW，即此结构的 Unicode 版本。 字符串参数定义为 PWSTR 数据类型，并使用 addrinfoexW 结构。

如果未定义 UNICODE 或_UNICODE，addrinfoex 定义为 addrinfoexA，即此结构的 ANSI 版本。 字符串参数是 PCSTR 数据类型，并且使用了 addrinfoexA 结构。

成功调用 GetAddrInfoEx后，addrinfoex 结构的链接列表在传递给 getAddrInfoEx 函数的ppResult 参数中返回。 可以按照每个返回 addrinfoex 结构的 ai_next 成员中提供的指针来处理列表，直到遇到 NULL 指针。 在每个返回 addrinfoex 结构中，ai_family、ai_socktype和 ai_protocol 成员对应于 套接字 或 WSASocket 函数调用中的相应参数。 此外，每个返回 addrinfoex 结构中的 ai_addr 成员指向填充的套接字地址结构，其 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