ADDRINFOEX2A 結構 (ws2def.h)

發行項
08/28/2023

當要求標準名稱和完整功能變數名稱時，GetAddrInfoEx函式會使用addrinfoex2結構來保存主機位址資訊。

語法

typedef struct addrinfoex2A {
  int                 ai_flags;
  int                 ai_family;
  int                 ai_socktype;
  int                 ai_protocol;
  size_t              ai_addrlen;
  char                *ai_canonname;
  struct sockaddr     *ai_addr;
  void                *ai_blob;
  size_t              ai_bloblen;
  LPGUID              ai_provider;
  struct addrinfoex2A *ai_next;
  int                 ai_version;
  char                *ai_fqdn;
} ADDRINFOEX2A, *PADDRINFOEX2A, *LPADDRINFOEX2A;

成員

ai_flags

旗標，指出 GetAddrInfoEx 函式中使用的選項。

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

值	意義
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 命名空間提供者會傳回以增強安全性取得的結果，以將可能的詐騙降到最低。當此選項是在GetAddrInfoEx的pHints參數中設定時，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_family

位址系列。

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

目前支援的值 AF_INET 或 AF_INET6，這是 IPv4 和 IPv6 的網際網路位址系列格式。如果已安裝位址系列的 Windows Sockets 服務提供者， (AF_NETBIOS 用於 NetBIOS 的其他選項，例如，如果已安裝位址系列的 Windows 通訊端服務提供者，則支援) 。請注意，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 (IrDA) 位址系列。只有在電腦已安裝基礎結構埠和驅動程式時，才支援此位址系列。
AF_BTH 32	藍牙位址系列。只有在安裝藍牙介面卡時，才支援此位址系列。

ai_socktype

通訊端類型。通訊端類型的可能值定義在 Winsock2.h 包含檔案中。

下表列出 Windows Sockets 2 支援的通訊端類型可能值：

值	意義
SOCK_STREAM 1	使用 OOB 資料傳輸機制，提供循序、可靠、雙向、以連線為基礎的位元組資料流程。針對網際網路位址系列使用傳輸控制通訊協定 (TCP) (AF_INET 或 AF_INET6) 。如果 ai_family 成員是AF_IRDA，則SOCK_STREAM 是唯一支援的通訊端類型。
SOCK_DGRAM 2	支援資料包，這些資料包是無連接、不可靠的固定 (通常很小) 最大長度。針對網際網路位址系列 (AF_INET或AF_INET6) ，使用使用者資料包通訊協定 (UDP) 。
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 上，標頭檔的組織已變更，而且此成員可以是Ws2def.h標頭檔中定義的IPPROTO列舉類型之一值。請注意， 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結構的指標。每個傳回addrinfoex2結構中的ai_addr成員會指向填入的通訊端位址結構。每個傳回 addrinfoex2 結構的長度，以位元組為單位，會指定在 ai_addrlen 成員中。

ai_blob

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

ai_bloblen

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

ai_provider

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

ai_next

連結清單中的下一個結構的指標。此參數會在連結清單的最後一個addrinfoex2結構中設定為Null。

ai_version

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

ai_fqdn

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

備註

Windows 8 和 Windows Server 2012 支援 addrinfoex2 結構

addrinfoex2結構是由GetAddrInfoEx函式用來保存主機位址資訊，當AI_FQDN和AI_CANONNAME位都設定在hints參數中提供給GetAddrInfoEx函式之選擇性addrinfoex結構的ai_flags成員中。 addrinfoex2結構是addrinfoex結構的增強版本，可同時傳回正式名稱和主機的完整功能變數名稱。額外的結構成員適用于結構的版本號碼，以及主機的完整功能變數名稱。

搭配GetAddrInfoEx函式使用的addrinfoex2結構是與getaddrinfo和GetAddrInfoW函式搭配使用的addrinfo和addrinfoW結構的增強版本。 GetAddrInfoEx函式允許指定命名空間提供者來解析查詢。為了與 IPv6 和 IPv4 通訊協定搭配使用，名稱解析可以是網域名稱系統 (DNS) 、本機主機檔案、電子郵件提供者 (NS_EMAIL 命名空間) 或其他命名機制。

tha ai_blob 成員中的 Blob 資料可用來傳回與名稱相關聯的其他提供者特定命名空間資訊。 ai_blob成員中的資料格式是特定命名空間提供者特有的。目前， NS_EMAIL 命名空間提供者會使用 Blob 資料來提供其他資訊。

定義 UNICODE 或_UNICODE時，addrinfoex2 會定義為 addrinfoex2W，這是這個結構的 Unicode 版本。字串參數會定義至 PWSTR 資料類型，並使用 addrinfoex2W 結構。

未定義 UNICODE 或_UNICODE時， addrinfoex2 會定義為 addrinfoex2A，這是這個結構的 ANSI 版本。字串參數屬於 char * 資料類型，並使用 addrinfoex2A 結構。

成功呼叫GetAddrInfoEx時，會將 addrinfoex2結構的連結清單傳回至GetAddrInfoEx函式的ppResult參數中。您可以依照每個傳回addrinfoex2結構的ai_next成員中提供的指標來處理清單，直到遇到Null指標為止。在每個傳回 的 addrinfoex2 結構中， ai_family、 ai_socktype和 ai_protocol 成員會對應到通訊端或 WSASocket 函式呼叫中的個別引數。此外，每個傳回addrinfoex2結構中的ai_addr成員會指向填入的通訊端位址結構，其ai_addrlen成員中指定的長度。

規格需求


最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
標頭	ws2def.h

另請參閱

ADDRINFOEX2A 結構 (ws2def.h)

語法

成員

備註

規格需求

另請參閱

意見反應

意見反應

其他資源