WSAStringToAddressW 函式 (winsock2.h)

發行項
08/27/2023

WSAStringToAddress函式會將標準文字呈現形式中的網路位址轉譯成sockaddr結構中的數值二進位格式，適合傳遞至採用這類結構的 Windows Sockets 常式。

語法

INT WSAAPI WSAStringToAddressW(
  [in]           LPWSTR              AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

參數

[in] AddressString

以零結尾字串的指標，其中包含要轉換之標準文字格式的網路位址。

[in] AddressFamily

AddressString參數所指向之網路位址的位址系列。

[in, optional] lpProtocolInfo

與要使用的提供者相關聯的 WSAPROTOCOL_INFO 結構。如果這是 Null，則呼叫會路由傳送至支援所指定 AddressFamily之第一個通訊協定的提供者。

[out] lpAddress

如果函式成功，則為位址字串填入 sockaddr 結構的緩衝區指標。

[in, out] lpAddressLength

lpAddress參數所指向之緩衝區長度的指標，以位元組為單位。如果函式呼叫成功，此參數會傳回lpAddress參數中所傳回之 sockaddr結構的指標。如果指定的緩衝區不夠大，則函式會失敗，並出現 WSAEFAULT 的特定錯誤，且此參數會以所需的位元組大小更新。

傳回值

如果作業成功， WSAStringToAddress 的傳回值會是零。否則，會傳回SOCKET_ERROR值，而且可以呼叫 WSAGetLastError來擷取特定的錯誤號碼。

錯誤碼	意義
WSAEFAULT	lpAddress參數所指向的緩衝區太小。傳入較大的緩衝區。
WSAEINVAL	函式無法將字串轉譯為 sockaddr。如需詳細資訊，請參閱下列一節。
WSANOTINITIALISED	WS2_32.DLL 尚未初始化。應用程式必須先呼叫 WSAStartup ，才能呼叫任何 Windows Socket 函式。
WSA_NOT_ENOUGH_MEMORY	記憶體不足，無法執行作業。

備註

WSAStringToAddress函式會將標準文字格式的網路位址轉譯成sockaddr結構中的數值二進位格式。

如果可能，位址的任何遺漏元件都會預設為合理的值。例如，遺漏的埠號碼預設為零。如果呼叫端希望特定提供者完成翻譯，它應該在lpProtocolInfo參數中提供對應的WSAPROTOCOL_INFO結構。

WSAStringToAddress函式會失敗 (並傳回 WSAEINVAL) 如果SOCKADDR_IN結構的sin_family成員，該SOCKADDR_IN結構是以sockaddr結構的形式傳入lpAddress參數，則不會設定為 AF_INET 或 AF_INET6。

在 Windows XP 上新增 WSAStringToAddress 函式的 IPv6 位址支援， (SP1) 和更新版本。 IPv6 也必須安裝在本機電腦上， WSAStringToAddress 函式才能支援 IPv6 位址。

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

Windows 8.1和Windows Server 2012 R2：Windows 市集應用程式支援此功能，Windows 8.1、Windows Server 2012 R2 及更新版本。

注意

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

規格需求


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