WSAStringToAddressA 函式（winsock2.h）

發行項
11/20/2024

WSAStringToAddress 函式會將標準文字呈現形式中的網路位址轉換成其數位二進位格式，以 sockaddr 結構，適用於傳遞至採用這類結構的 Windows Sockets 例程。

語法

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA 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 結構的形式傳入 lpAddress 參數，則不會設定為AF_INET或AF_INET6。

使用 WSAStringToAddress 函式支援 IPv6 位址已新增至 Windows XP Service Pack 1 （SP1）和更新版本。 IPv6 也必須安裝在本機計算機上，WSAStringToAddress 函式以支援 IPv6 位址。

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

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	winsock2.h
連結庫	Ws2_32.lib
DLL	Ws2_32.dll