WSAAddressToStringA 函式 (winsock2.h)

發行項
03/13/2024

WSAAddressToString 函式會將 sockaddr 結構的所有元件轉換成人類可讀取的位址字串表示。

這主要用於顯示用途。如果呼叫端要求特定提供者執行翻譯，它應該在 lpProtocolInfo 參數中提供對應的WSAPROTOCOL_INFO結構。

語法

INT WSAAPI WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

參數

[in] lpsaAddress

要轉譯成字串之 sockaddr 結構的指標。

[in] dwAddressLength

lpsaAddress 參數所指向之 sockaddr 結構中地址的長度，以位元組為單位。 dwAddressLength 參數的大小可能會因不同的通訊協定而有所不同。

[in, optional] lpProtocolInfo

特定提供者 WSAPROTOCOL_INFO 結構的指標。如果此參數為 NULL，則會將呼叫路由傳送至支援 lpsaAddress 參數中所指示位址系列之第一個通訊協定的提供者。

[in, out] lpszAddressString

接收人類可讀取位址字串之緩衝區的指標。

[in, out] lpdwAddressStringLength

在輸入時，此參數會指定 lpszAddressString 參數所指向的緩衝區長度。長度是以 ANSI 字串的位元組表示，而以 Unicode 字串的 WCHAR 表示。在輸出時，此參數會傳回字串的長度，包括實際複製到 lpszAddressString 參數所指向之緩衝區的 NULL 終止符。如果指定的緩衝區不夠大，函式會失敗，並出現 WSAEFAULT 的特定錯誤，而且此參數會以所需的大小更新。

傳回值

如果沒有發生錯誤， WSAAddressToString 會傳回零的值。否則，會傳回SOCKET_ERROR值，並呼叫 WSAGetLastError 來擷取特定的錯誤號碼。

錯誤碼	意義
WSAEFAULT	指定的 lpcsAddress、 lpProtocolInfo 和 lpszAddressString 參數指向不是行程地址空間中的所有記憶體，或 lpszAddressString 參數所指向的緩衝區太小。傳入較大的緩衝區。
WSAEINVAL	傳遞了一個無效的參數。如果 lpsaAddress、 dwAddressLength 或 lpdwAddressStringLength 參數為 NULL，就會傳回此錯誤。如果指定的位址不是有效的套接字位址，或傳輸提供者不支援指定的位址系列，也會傳回此錯誤。
WSAENOBUFS	沒有可用的緩衝區空間。
WSANOTINITIALISED	Winsock 2 DLL 尚未初始化。應用程式必須先呼叫 WSAStartup ，再呼叫任何 Windows Sockets 函式。

備註

WSAAddressToString 函式提供與通訊協議無關的位址對字串轉譯。 WSAAddressToString 函式會採用 lpsaAddress 參數指向的套接字地址結構，並傳回代表 lpszAddressString 參數中套接字位址的 NULL 終止字元串指標。雖然 inet_ntoa 函式只適用於 IPv4 位址， 但 WSAAddressToString 函式適用於本機電腦上的 Winsock 提供者所支援的任何套接字位址，包括 IPv6 位址。

如果 lpsaAddress 參數指向 IPv4 套接字位址， (位址系列 AF_INET) ，則 lpszAddressString 參數所指向之緩衝區中所傳回的位址字符串會以 dotted-decimal 表示法表示，如同 “192.168.16.0”，這是以 dotted-decimal 表示法表示法傳回的 IPv4 位址範例。

如果 lpsaAddress 參數指向 IPv6 套接字位址， (位址系列 AF_INET6) ，則 lpszAddressString 參數所指向緩衝區中所傳回的位址字元串會是因特網標準格式。基本字串表示是由 8 個十六進位數位所組成，並以冒號分隔。連續零數位的字串會取代為雙冒號。 IPv6 位址的字串表示中只能有一個雙冒號。

如果 lpszAddressString 參數指向的緩衝區長度不足以接收套接字位址的字串表示， WSAAddressToString 會傳回 WSAEFAULT。

Windows XP 上新增了使用 WSAAddressToString 函式的 IPv6 位址支援， (SP1) 和更新版本。 IPv6 也必須安裝在本機計算機上， WSAAddressToString 函式才能支援 IPv6 位址。

Windows Phone 8：Windows Phone Windows Phone 8 和更新版本上的市集應用程式支援 WSAAddressToStringW 函式。

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

注意

winsock2.h 標頭會根據 UNICODE 預處理器常數的定義，將 WSAAddressToString 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

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