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。
| 價值觀 | Meaning |
|---|---|
|
網際網路協定版本4（IPv4）位址家族。 當指定此參數時，函式會回傳一個 IPv4 位址字串。 |
|
網際網路協定版本 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 回傳的擴展錯誤碼可為以下其中之一。
| 錯誤碼 | Meaning |
|---|---|
| Family 參數中指定的位址族不支援。 若家族參數未AF_INET或未AF_INET6，則會回傳此錯誤。 | |
|
無效的參數已傳遞至函式。 若 pStringBuf 中傳遞 NULL 指標或 StringBufSize 參數為零，則會回傳此錯誤。 若 pStringBuf 參數所指向的緩衝區長度不足以接收 IP 位址的字串表示，也會回傳此錯誤。 |
備註
InetNtop 功能支援 Windows Vista 及更新版本。
InetNtop 函式提供與協定無關的位址轉字串轉換。 InetNtop 函式會取用由 pAddr 參數指定的網際網路位址結構，並回傳一個 NULL 終止的字串，代表該 IP 位址。 雖然 inet_ntoa 函式僅適用於 IPv4 位址，而 InetNtop 函式則適用於 IPv4 或 IPv6 位址。
此函數的 ANSI 版本依據 RFC 2553 所定義 inet_ntop 。 欲了解更多資訊，請參閱 IETF 網站上的 RFC 2553。
InetNtop 函式不需要載入 Windows Sockets 的 DLL 來執行 IP 位址轉字串轉換。
若指定的 Family 參數為 AF_INET，則 pAddr 參數必須指向帶有 IPv4 位址的 IN_ADDR 結構進行轉換。 pStringBuf 參數指向的緩衝區中回傳的位址字串以虛點十進位符號表示，如「192.168.16.0」，這是 IPv4 地址的虛點十進位符號範例。
若 Family 參數為 AF_INET6，則 pAddr 參數必須指向帶有 IPv6 位址的 IN6_ADDR 結構以進行轉換。 pStringBuf 參數指向的緩衝區中回傳的位址字串為網際網路標準格式。 基本字串表示由 8 個十六進位數字組成，由冒號分隔。 一串連續的零數字會以雙冒號取代。 IPv6 位址的字串表示法中只能有一個雙冒號。 如果位址是相容 IPv4，最後 32 位元會以 IPv4 風格的虛點八位元組表示。
如果 pStringBuf 參數指向的緩衝區長度不足以接收 IP 位址的字串表示， InetNtop 會回傳 ERROR_INVALID_PARAMETER。
當 UNICODE 或 _UNICODE 定義時， InetNtop 定義為 InetNtopW，即此函式的 Unicode 版本。 pStringBuf 參數定義為 PWSTR 資料型態。
當未定義 UNICODE 或 _UNICODE 時， InetNtop 會定義為 InetNtopA，即此函式的 ANSI 版本。 ANSI 版本的函數總是定義為 inet_ntop。 pStringBuf 參數是依據 PSTR 資料型別定義的。
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 位址、範圍 ID 和埠轉換為標準格式的 IPv6 字串。
Windows 8.1 與 Windows Server 2012 R2： InetNtopW 功能支援 Windows 8.1、Windows Server 2012 R2 及更新版本的 Windows 商店應用程式。
需求
| Requirement | 價值觀 |
|---|---|
| 最低支援的用戶端 | Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| Header | WS2TCPIP.H |
| Library | Ws2_32.lib |
| DLL | Ws2_32.dll |