ADDRINFOEX5結構 （ws2def.h）

  • 發行項

GetAddrInfoEx 函式會使用 addrinfoex4 結構，以在要求特定網路介面時保存主機地址資訊。

語法

typedef struct addrinfoex5 {
  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 addrinfoex5 *ai_next;
  int                ai_version;
  PWSTR              ai_fqdn;
  int                ai_interfaceindex;
  HANDLE             ai_resolutionhandle;
  unsigned int       ai_ttl;
} ADDRINFOEX5, *PADDRINFOEX5, *LPADDRINFOEX5;

成員

ai_flags

指出 getAddrInfoEx 函式中所使用 選項的旗標。

ai_flags 成員的支援值定義於 Winsock2.h include 檔案中，而且可以是下列選項的組合。

價值 意義
AI_PASSIVE
0x01
 套接字位址將用於呼叫 系結函式。
AI_CANONNAME
0x02
 標準名稱會在第一個 ai_canonname 成員中傳回。
AI_NUMERICHOST
0x04
 傳遞至 GetAddrInfoEx 函式的 nodename 參數必須是數值字串。
AI_ALL
0x0100
 如果設定此位，則會針對具有 AI_V4MAPPED的 IPv6 位址和 IPv4 位址提出要求。

Windows Vista 和更新版本支援此選項。
AI_ADDRCONFIG
0x0400
 只有在設定全域位址時，GetAddrInfoEx 才會解析。 IPv6 和 IPv4 回送位址不會被視為有效的全域位址。

Windows Vista 和更新版本支援此選項。
AI_V4MAPPED
0x0800
 如果 IPv6 位址的 GetAddrInfoEx 要求失敗，則會對 IPv4 位址提出名稱服務要求，而且這些位址會轉換成 IPv4 對應的 IPv6 位址格式。

Windows Vista 和更新版本支援此選項。
AI_NON_AUTHORITATIVE
0x04000
 地址資訊來自非授權結果。

在 getAddrInfoEx的 pHints 參數中設定此選項時，NS_EMAIL 命名空間提供者會同時傳回授權和非授權結果。 如果未設定此選項，則只會傳回授權結果。

只有 Windows Vista 和更新版本的 NS_EMAIL 命名空間才支援此選項。
AI_SECURE
0x08000
 地址信息來自安全通道。

如果設定 AI_SECURE 位，NS_EMAIL 命名空間提供者會傳回使用增強安全性取得的結果，以將可能的詐騙降到最低。

當此選項設定於 GetAddrInfoExpHints 參數時，NS_EMAIL 命名空間提供者只會傳回使用增強安全性取得的結果，以將可能的詐騙降到最低。

只有 Windows Vista 和更新版本的 NS_EMAIL 命名空間才支援此選項。
AI_RETURN_PREFERRED_NAMES
0x010000
 地址資訊適用於具有特定命名空間之發行集的慣用名稱。

在 getAddrInfoEx的 pHints 參數中設定此選項時，pName 參數中不應提供任何名稱，NS_EMAIL 命名空間提供者會傳回發行集的慣用名稱。

只有 Windows Vista 和更新版本的 NS_EMAIL 命名空間才支援此選項。
AI_FQDN
0x00020000
 完整功能變數名稱會在第一個 ai_fqdn 成員中傳回。

當此選項設定於 GetAddrInfoEx 的 pHints 參數中，並在 pName 參數中指定一般名稱（單一卷標），則會傳回最終解析為名稱的完整功能變數名稱。

Windows 7、Windows Server 2008 R2 及更新版本支援此選項。
AI_FILESERVER
0x00040000
 命名空間提供者的提示，指出正在查詢的主機名正用於檔案共用案例中。 命名空間提供者可能會忽略這個提示。

Windows 7、Windows Server 2008 R2 及更新版本支援此選項。
AI_DISABLE_IDN_ENCODING
0x00080000
 在 getAddrInfoEx 函式所呼叫的名稱解析函式中使用 Punycode 停用自動國際功能變數名稱編碼。

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_RETURN_TTL
0x0080
 DNS 記錄有效秒數。 如果此旗標存在，GetAddrInfoEx。ppResult 參數會傳回 addrinfoex5 結構 清單，其中 ai_ttl 成員將包含 DNS 記錄的個別 TTL。

ai_family

位址系列。

位址系列可能的值定義於 Ws2def.h 頭檔中。 請注意，Ws2def.h 頭文件會自動包含在 Winsock2.h中，而且不應該直接使用。

目前支援的值是 AF_INET 或 AF_INET6，這是 IPv4 和 IPv6 的因特網位址系列格式。 如果已安裝位址系列 Windows Sockets 服務提供者，則支援位址系列的其他選項（例如，AF_NETBIOS 與 NetBIOS 搭配使用）。 請注意，AF_位址系列和PF_通訊協定系列常數的值相同（例如，AF_INET 和 PF_INET），因此可以使用任一常數。

下表列出位址家族的常見值，但可能有許多其他值。

價值 意義
AF_UNSPEC
0
 未指定位址系列。
AF_INET
2
 因特網通訊協定第 4 版 （IPv4） 位址系列。
AF_NETBIOS
17
 NetBIOS 位址系列。 只有在已安裝 NetBIOS 的 Windows Sockets 提供者時，才支援此位址系列。
AF_INET6
23
 因特網通訊協定第 6 版 （IPv6） 位址系列。
AF_IRDA
26
 紅外數據協會 （IrDA） 位址系列。 只有在計算機已安裝紅外埠和驅動程式時，才支援此位址系列。
AF_BTH
32
 藍牙位址系列。 只有在已安裝藍牙配接器時，才支援此位址系列。

ai_socktype

套接字類型。 套接字類型的可能值定義於 Winsock2.h include 檔案中。

下表列出 Windows Sockets 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
 提供可靠的訊息數據報。 此類型的範例是 Windows 中的務實一般多播（PGM）多播通訊協議實作，通常稱為 可靠的多播程式設計。
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 Vista 和更新版本的 Windows SDK 上，頭文件的組織已變更，而且此成員可以是 IPPROTO 列舉類型中定義的其中一個值，Ws2def.h 頭檔。 請注意，Ws2def.h 頭文件會自動包含在 Winsock2.h中，而且不應該直接使用。

如果針對 ai_protocol指定了 0 值，則呼叫端不想要指定通訊協議，服務提供者會選擇要使用的 ai_protocol。 針對 IPv4 和 IPv6 以外的通訊協定，請將 ai_protocol 設為零。

下表列出 ai_protocol 成員的一般值，但可能有許多其他值。

價值 意義
IPPROTO_TCP
6
 傳輸控制通訊協定 （TCP） 。 當 ai_family 成員 AF_INET 或 AF_INET6 且 ai_socktype 成員 SOCK_STREAM時，這個值是可能的。
IPPROTO_UDP
17
 用戶數據報通訊協定 （UDP）。 當 ai_family 成員 AF_INET 或 AF_INET6，且 類型 參數 SOCK_DGRAM時，這是可能的值。
IPPROTO_RM
113
 可靠多播的PGM通訊協定。 當 ai_family 成員 AF_INET 且 ai_socktype 成員 SOCK_RDM時，這是可能的值。 在 Windows Vista 和更新版本的 Windows SDK 上，這個值也稱為 IPPROTO_PGM。
 

如果 ai_family 成員是 AF_IRDA，則 ai_protocol 必須是 0。

ai_addrlen

ai_addr 成員所指向之緩衝區的長度，以位元組為單位。

ai_canonname

主機的正式名稱。

ai_addr

sockaddr 結構的指標。 每個傳回 addrinfoex4 結構中的 ai_addr 成員會指向填入的套接字地址結構。 addrinfoex4 ai_addrlen 結構中，每個傳回 的長度，以位元組為單位。

ai_blob

數據指標，用來傳回與位址清單以外的名稱相關聯的提供者特定命名空間資訊。 ai_blob 所指向之緩衝區的長度，以位元組為單位，必須在 ai_bloblen 成員中指定。

ai_bloblen

ai_blob 成員的長度，以位元組為單位。

ai_provider

特定命名空間提供者之 GUID 的指標。

ai_next

連結清單中下一個結構的指標。 此參數設定為 連結清單最後一個 addrinfoex4 結構中的 NULL。

ai_version

這個結構的版本號碼。 目前用於此結構版本的值為 4。

ai_fqdn

主機的完整功能變數名稱。

ai_interfaceindex

介面索引，如 IP_ADAPTER_ADDRESSES所定義。GetAdaptersAddresses中傳回 的 IfIndex 属性。

ai_resolutionhandle

處理指向主機的完整功能變數名稱。

ai_ttl

此 DNS 記錄有效秒數。

言論

GetAddrInfoExW 函式會使用 ADDRINFOEX5 結構，在透過 GetAddrInfoExW提示 參數傳入的 ai_flags 成員中設定 AI_EXTENDED 或 AI_RETURN_TTL 位時，保留主機地址資訊。

ADDRINFOEX5 結構是 ADDRINFOEX4 結構的延伸。 除了 ADDRINFOEX4 結構中的所有欄位之外，它也會保留每個傳回 IP 位址的個別 DNS TTL 成員 ai_ttl 成員。

如果在透過 GetAddrInfoExhints 參數傳入的 ai_flags 成員中設定 AI_RETURN_TTL 位，GetAddrInfoExWppResult 參數會傳回 ADDRINFOEX5 結構清單。 此清單中的每個節點都會包含在 ai_ttl 成員中，sockaddr 成員中存在的 IP 位址個別 DNS TTL。

例子

請參閱 ADDRINFOEX4 結構主題中的範例程序代碼。

要求

要求 價值
最低支援的用戶端 Windows 10 組建 20348
支援的最低伺服器 Windows 10 組建 20348
標頭 ws2def.h

另請參閱

GetAddrInfoEx

addrinfo

addrinfoW

addrinfoex

addrinfoex3