inetNtopW 函式 (ws2tcpip.h)

發行項
03/04/2024

InetNtop 函式會將 IPv4 或 IPv6 因特網網路位址轉換成以因特網標準格式的字串。此函式的 ANSI 版本 inet_ntop。

語法

PCWSTR WSAAPI InetNtopW(
  [in]  INT        Family,
  [in]  const VOID *pAddr,
  [out] PWSTR      pStringBuf,
  [in]  size_t     StringBufSize
);

參數

[in] Family

位址系列。

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

目前支援的值 AF_INET 和 AF_INET6。

值	意義
AF_INET 2	因特網通訊協定第 4 版 (IPv4) 位址系列。指定此參數時，此函式會傳回IPv4位址字串。
AF_INET6 23	因特網通訊協定第 6 版 (IPv6) 位址系列。指定此參數時，此函式會傳回IPv6位址字串。

[in] pAddr

要轉換成字串之網路位元組中IP位址的指標。

當 Family 參數 AF_INET時， pAddr 參數必須指向具有 IPv4 位址轉換的IN_ADDR 結構。

當 Family 參數 AF_INET6時， pAddr 參數必須指向具有要轉換之 IPv6 位址的IN6_ADDR 結構。

[out] pStringBuf

緩衝區的指標，用來儲存IP位址的 NULL終止字串表示。

對於 IPv4 位址，此緩衝區的大小應該足以容納至少 16 個字元。

對於 IPv6 位址，此緩衝區的大小應該足以保存至少 46 個字元。

[in] StringBufSize

在輸入時， pStringBuf 參數所指向之緩衝區的長度，以字元為單位。

傳回值

如果沒有發生錯誤， InetNtop 函式會傳回緩衝區的指標，其中包含標準格式之IP位址的字串表示。

否則，會傳回 NULL 值，而且可以藉由呼叫來擷取特定的錯誤碼
WSAGetLastError 以取得擴充錯誤資訊。

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

錯誤碼	意義
WSAEAFNOSUPPORT	不支援Family參數中指定的位址系列。如果指定的 Family 參數未 AF_INET 或 AF_INET6，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	無效的參數已傳遞至函式。如果在 pStringBuf 中傳遞 NULL 指標，或 StringBufSize 參數為零，就會傳回此錯誤。如果 pStringBuf 參數指向的緩衝區長度不足以接收 IP 位址的字串表示，也會傳回此錯誤。

備註

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

InetNtop 函式提供與通訊協定無關的位址對字串轉譯。 InetNtop 函式會採用 pAddr 參數所指定的因特網地址結構，並傳回代表 IP 位址的 NULL 終止字串。雖然 inet_ntoa 函式只適用於 IPv4 位址， 但 InetNtop 函式適用於 IPv4 或 IPv6 位址。

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

InetNtop 函式不需要載入 Windows Sockets DLL 以執行 IP 位址到字串轉換。

如果指定的 Family 參數 AF_INET， 則 pAddr 參數必須指向具有要轉換之 IPv4 位址的IN_ADDR 結構。 pStringBuf 參數所指向之緩衝區中所傳回的位址字串是以點數表示法表示法，如同 “192.168.16.0”，這是以 dotted-decimal 表示法表示的 IPv4 位址範例。

如果指定的 Family 參數 AF_INET6， 則 pAddr 參數必須指向具有要轉換之 IPv6 位址的 IN6_ADDR 結構。 pStringBuf 參數所指向之緩衝區中所傳回的位址字串是因特網標準格式。基本字串表示包含 8 個十六進位數位，並以冒號分隔。連續零數位的字串會以雙冒號取代。 IPv6 位址的字串表示中只能有一個雙冒號。如果位址是 IPv4 相容的位址，則最後 32 個位會以 IPv4 樣式的 dotted-octet 表示法表示。

如果 pStringBuf 參數所指向的緩衝區長度不足以接收 IP 位址的字串表示， InetNtop 會傳回ERROR_INVALID_PARAMETER。

定義 UNICODE 或_UNICODE時， InetNtop 會定義為 InetNtopW，這是此函式的 Unicode 版本。 pStringBuf 參數會定義為 PSTR 數據類型。

未定義 UNICODE 或_UNICODE時， InetNtop 會定義為 InetNtopA，這是此函式的 ANSI 版本。此函式的 ANSI 版本一律定義為 inet_ntop。 pStringBuf 參數會定義為 PWSTR 數據類型。

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

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

在 Windows Vista 和更新版本上， RtlIpv4AddressToString 和 RtlIpv4AddressToStringEx 函式可用來將以 IN_ADDR 結構表示的 IPv4 位址轉換為因特網標準點小數表示法中的 IPv4 位址字元串表示法。在 Windows Vista 和更新版本上， RtlIpv6AddressToString 和 RtlIpv6AddressToStringEx 函式可用來將以 IN6_ADDR 結構表示的 IPv6 位址轉換為 IPv6 位址的字串表示。 RtlIpv6AddressToStringEx 函式更有彈性，因為它也會以標準格式將 IPv6 位址、範圍標識符和埠轉換成 IPv6 字串。

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

規格需求

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