inetPtonW 函式 (ws2tcpip.h)

發行項
03/13/2024

InetPton 函式會將標準文字簡報表單中的 IPv4 或 IPv6 因特網網路位址轉換成其數值二進位格式。此函式的 ANSI 版本 inet_pton。

語法

INT WSAAPI InetPtonW(
  [in]  INT    Family,
  [in]  PCWSTR pszAddrString,
  [out] PVOID  pAddrBuf
);

參數

[in] Family

位址系列。

位址系列的可能值定義於 Ws2def.h 頭檔中。請注意， Ws2def.h 頭文件會自動包含在 Winsock2.h 中，不應直接使用。請注意，AF_位址系列和PF_通訊協定系列常數的值 (相同，例如， AF_INET 和 PF_INET) ，因此可以使用任一個常數。

目前支援的值 AF_INET 和 AF_INET6。

值	意義
AF_INET 2	因特網通訊協定第 4 版 (IPv4) 位址系列。指定此參數時， pszAddrString 參數必須指向IPv4 位址的文字表示法，而 pAddrBuf 參數會傳回代表 IPv4 位址的IN_ADDR 結構的指標。
AF_INET6 23	因特網通訊協定第 6 版 (IPv6) 位址系列。指定此參數時， pszAddrString 參數必須指向IPv6 位址的文字表示法，而 pAddrBuf 參數會傳回代表 IPv6 位址之IN6_ADDR 結構的指標。

[in] pszAddrString

NULL 終止字串的指標，其中包含要轉換成數值二進位格式之 IP 位址的文字表示。

當 Family 參數 AF_INET時， pszAddrString 參數必須指向標準 dotted-decimal 表示法中 IPv4 位址的文字表示法。

當 Family 參數 AF_INET6時， pszAddrString 參數必須指向標準表示法中 IPv6 位址的文字表示法。

[out] pAddrBuf

緩衝區的指標，用來儲存IP位址的數值二進位表示法。 IP 位址會依網路位元組順序傳回。

當 Family 參數 AF_INET時，這個緩衝區應該夠大，足以保存 IN_ADDR 結構。

當 Family 參數 AF_INET6時，這個緩衝區應該夠大，足以保存 IN6_ADDR 結構。

傳回值

如果沒有發生錯誤， InetPton 函式會傳回值 1，而 pAddrBuf 參數所指向的緩衝區會以網路位元組順序包含二進位數值 IP 位址。

如果 pAddrBuf 參數指向不是有效 IPv4 點十進位字串或有效的 IPv6 位址字串的字串，InetPton 函式會傳回 0 的值。否則，會傳回 -1 的值，而且可以呼叫來擷取特定的錯誤碼
WSAGetLastError 以取得擴充錯誤資訊。

如果函式發生錯誤， WSAGetLastError 傳回的擴充錯誤碼可以是下列其中一個值。

錯誤碼	意義
WSAEAFNOSUPPORT	不支援Family參數中指定的位址系列。如果指定的 Family 參數未 AF_INET 或 AF_INET6，就會傳回此錯誤。
WSAEFAULT	pszAddrString 或 pAddrBuf 參數為 NULL，或不是使用者地址空間的一部分。

備註

Windows Vista 和更新版本支援 InetPton 函式。

InetPton 函式會在其標準文字呈現表單中提供因特網網路地址的通訊協定獨立轉換，轉換為其數值二進位格式。 InetPton 函式會採用 pszAddrString 參數所指向之因特網位址的文字表示法，並傳回 pAddrBuf 參數中數值二進位 IP 位址的指標。雖然 inet_addr 函式只適用於 IPv4 位址字串， 但 InetPton 函式適用於 IPv4 或 IPv6 位址字串。

此函式的 ANSI 版本inet_pton如 RFC 2553 中所定義。如需詳細資訊，請參閱 IETF 網站提供的 RFC 2553。

InetPton 函式不需要載入 Windows Sockets DLL，才能執行文字字串的轉換，該字串代表 IP 位址為數值二進位 IP 位址。

如果指定的 Family 參數 是AF_INET， 則 pszAddrString 參數必須以虛線表示法指向IPv4 位址的文字字串串，如同 “192.168.16.0”，這是以 dotted-decimal 表示法表示的 IPv4 位址範例。

如果指定的 Family 參數 是AF_INET6， 則 pszAddrString 參數必須以因特網標準格式指向IPv6位址的文字字串。基本字串表示包含 8 個十六進位數位，並以冒號分隔。連續零數位的字串可以取代為雙冒號。 IPv6 位址的字串表示中只能有一個雙冒號。如果位址是 IPv4 相容的位址，則最後 32 個位可能會以 IPv4 樣式的 dotted-octet 表示法表示。

定義 UNICODE 或_UNICODE時， InetPton 會定義為 InetPtonW，這是此函式的 Unicode 版本。 pszAddrString 參數會定義為PCWSTR數據類型。

未定義 UNICODE 或_UNICODE時， InetPton 會定義為 InetPtonA，這是此函式的 ANSI 版本。此函式的 ANSI 版本一律定義為 inet_pton。 pszAddrString 參數會定義為PCSTR數據類型。

IN_ADDR 結構定義於 Inaddr.h 頭檔中。

IN6_ADDR 結構定義於 In6addr.h 頭檔中。

在 Windows Vista 和更新版本上， RtlIpv4StringToAddress 和 RtlIpv4StringToAddressEx 函式可用來將因特網標準 dotted-decimal 表示法中的 IPv4 位址文字表示法轉換成以 IN_ADDR 結構表示的數位二進位位址。在 Windows Vista 和更新版本上， RtlIpv6StringToAddress 和 RtlIpv6StringToAddressEx 函式可用來將 IPv6 位址的字串表示轉換成以 IN6_ADDR 結構表示的數位二進位 IPv6 位址。 RtlIpv6StringToAddressEx 函式更有彈性，因為它也會將 IPv6 位址的字串表示法轉換成數值二進位格式，以包含範圍標識符和埠。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本的 Windows 市集應用程式支援 InetPtonW 函式。

規格需求

需求	值
最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	ws2tcpip.h
程式庫	Ws2_32.lib
Dll	Ws2_32.dll