WSAConnect 函式 (winsock2.h)

發行項
03/04/2024

WSAConnect 函式會建立與另一個套接字應用程式的連線、交換連接數據，並根據指定的 FLOWSPEC 結構指定必要的服務品質。

語法

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

參數

[in] s

識別未連接套接字的描述項。

[in] name

sockaddr 結構的指標，指定要連接的位址。針對 IPv4，sockaddr 包含位址系列、目的地 IPv4 位址和目的地埠 的AF_INET 。針對 IPv6，sockaddr 結構包含位址系列、目的地 IPv6 位址、目的地埠，以及可能包含其他流程和範圍標識符資訊AF_INET6。

[in] namelen

name 參數所指向之 sockaddr 結構的長度，以位元組為單位。

[in] lpCallerData

在連線建立期間傳送至另一個套接字之用戶數據的指標。請參閱＜備註＞。

[out] lpCalleeData

在連線建立期間，要從其他套接字傳輸回之用戶數據的指標。請參閱＜備註＞。

[in] lpSQOS

套接字之FLOWSPEC 結構的指標，每個方向各一個。

[in] lpGQOS

保留供未來與套接字群組搭配使用。如果適用的話，套接字群組之 FLOWSPEC 結構的指標 () 。此參數應該是 NULL。

傳回值

如果沒有發生錯誤， WSAConnect 會 傳回零。否則，它會傳回SOCKET_ERROR，而且可以呼叫 WSAGetLastError 來擷取特定的錯誤碼。在封鎖套接字上，傳回值表示連線嘗試成功或失敗。

使用非封鎖套接字時，無法立即完成連線嘗試。在此情況下， WSAConnect 會傳回SOCKET_ERROR，而 WSAGetLastError 會傳回 WSAEWOULDBLOCK;因此，應用程式可能會：

使用 select 來檢查套接字是否可寫入，以判斷連線要求的完成。
如果您的應用程式使用 WSAAsyncSelect 來指出對連線事件感興趣，則當連線作業順利完成 (或未) 時，您的應用程式會收到FD_CONNECT通知。
如果您的應用程式使用 WSAEventSelect 來指出對連線事件感興趣，當連線作業完成 (或未) 時，相關聯的事件物件將會發出訊號。

若為非封鎖套接字，直到連線嘗試完成相同套接字上 WSAConnect 的所有後續呼叫都會失敗，並出現錯誤碼 WSAEALREADY。

如果傳回錯誤碼指出連線嘗試失敗 (亦即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) 應用程式可以針對相同的套接字再次呼叫 WSAConnect 。

錯誤碼	意義
WSANOTINITIALISED	使用這個函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAENETDOWN	網路子系統失敗。
WSAEADDRINUSE	套接字的本機位址已在使用中，且套接字未標示為允許與SO_REUSEADDR重複使用位址。此錯誤通常會在執行系結期間發生，但如果系結函式在涉及ADDR_ANY) 的部分通配符地址上运作，而且此函式必須在此函式時「認可」特定 (位址，則可能會延遲到此函式。
WSAEINTR	(封鎖) Windows Socket 1.1 呼叫已透過 WSACancelBlockingCall 取消。
WSAEINPROGRESS	封鎖的 Windows Sockets 1.1 呼叫正在進行中，或服務提供者仍在處理回呼函式。
WSAEALREADY	在指定的套接字上正在進行非封鎖連線或 WSAConnect 呼叫。
WSAEADDRNOTAVAIL	遠程位址不是 (的有效位址，例如ADDR_ANY) 。
WSAEAFNOSUPPORT	指定之系列中的位址無法用於此通訊端。
WSAECONNREFUSED	嘗試連線已遭到拒絕。
WSAEFAULT	name 或 namelen 參數不是使用者位址空間的有效部分、namelen 參數太小、lpCalleeData、lpSQOS 和 lpGQOS 的緩衝區長度太小，或 lpCallerData 的緩衝區長度太大。
WSAEINVAL	參數 s 是接聽套接字，或指定的目的地位址與套接字所屬之受限制群組的位址不一致，或 lpGQOS 參數不是 NULL。
WSAEISCONN	套接字已 (連線導向套接字) 。
WSAENETUNREACH	此時無法透過此主機連接網路。
WSAEHOSTUNREACH	已嘗試對無法連接的主機進行通訊端作業。
WSAENOBUFS	沒有可用的緩衝區空間。套接字無法連接。
WSAENOTSOCK	描述項不是套接字。
WSAEOPNOTSUPP	無法滿足 lpSQOS 和 lpGQOS 中指定的 FLOWSPEC 結構。
WSAEPROTONOSUPPORT	服務提供者不支援 lpCallerData 參數。
WSAETIMEDOUT	嘗試連線逾時，而不需建立連線。
WSAEWOULDBLOCK	套接字標示為非封鎖，且無法立即完成連線。
WSAEACCES	嘗試將數據報套接字連線到廣播位址失敗，因為未啟用 setockopt SO_BROADCAST。

備註

WSAConnect 函式可用來建立與指定目的地的連線，以及執行一些在連接時間發生的其他輔助作業。如果套接字 s 是未繫結的，系統就會將唯一值指派給本機關聯，而且套接字會標示為系結。

針對以 Windows Vista 和更新版本為目標的應用程式，請考慮使用 WSAConnectByList 或 WSAConnectByName 函式，大幅簡化用戶端應用程式設計。

例如，針對連線導向套接字 (類型SOCK_STREAM) ，使用名稱 (套接字命名空間中的位址來起始對外部主機的作用中連線;如需詳細描述，請參閱系結) 。當此呼叫成功完成時，套接字便已準備好傳送/接收數據。如果名稱結構的 address 參數全部為零， WSAConnect 會傳回錯誤 WSAEADDRNOTAVAIL。任何嘗試重新連線使用中的連線都會失敗，並出現錯誤碼 WSAEISCONN。

注意如果開啟套接字，就會進行 setockopt 呼叫，然後進行 sendto 呼叫，Windows Sockets 會執行隱含系結函數調用。

針對連線導向的非封鎖套接字，通常無法立即完成連線。在這種情況下，此函式會傳回錯誤 WSAEWOULDBLOCK。不過，作業會繼續進行。當成功或失敗結果變成已知時，可能會根據用戶端註冊通知的方式，以數種方式之一回報。如果用戶端使用 select，則會在 writefds 集合中報告成功，並在 exceptfds 集合中報告失敗。如果用戶端使用 WSAAsyncSelect 或 WSAEventSelect，則會以FD_CONNECT宣告通知，而與FD_CONNECT相關聯的錯誤碼表示成功或失敗的特定原因。

例如，對於無連線套接字 (類型 SOCK_DGRAM) ，WSAConnect 所執行的作業只是建立預設目的地位址，讓套接字可用於後續連線導向的傳送和接收作業， (傳送、 WSASend、 recv 和 WSARecv) 。從指定之目的地位址以外的位址接收的任何數據報都會被捨棄。如果整個名稱結構都是零， (不只是名稱結構的 address 參數) ，則會中斷套接字的連線。然後，預設遠端位址將會不確定，因此傳送、 WSASend、 recv 和 WSARecv 呼叫將會傳回錯誤碼 WSAENOTCONN。不過，仍然可以使用 sendto、 WSASendTo、 recvfrom 和 WSARecvFrom 。只要再次呼叫 WSAConnect 即可變更預設目的地，即使套接字已連線也一樣。如果名稱與先前 的 WSAConnect 不同，則會捨棄任何排入收據的數據報。

針對無連線套接字，名稱可以指出任何有效的位址，包括廣播位址。不過，若要連線到廣播位址，套接字必須啟用 setockopt SO_BROADCAST。否則， WSAConnect 將會失敗，並出現錯誤碼 WSAEACCES。

在無連線套接字上，無法交換使用者對用戶數據，而且會以無訊息方式忽略對應的參數。

應用程式負責由它指定的任何參數，直接或間接配置指向的任何記憶體空間。

lpCallerData 參數包含任何要連同連線要求一起傳送之用戶數據的指標， (稱為連線數據) 。這是額外的數據，不是在一般網路數據流中，會隨著網路要求一起傳送來建立連線。舊版通訊協定會使用此選項，例如 DECNet、OSI TP4 和其他通訊協定。

注意 Windows 中的 TCP/IP 通訊協定不支援連線數據。只有透過原始套接字的 ATM (RAWWAN) 支援連線數據。

如果 lpCallerData 為 NULL，則不會將使用者數據傳遞至對等。 lpCalleeData 是一個結果參數，其中包含從另一個套接字傳回的任何用戶數據，作為 WSABUF 結構中聯機建立的一部分。 lpCalleeData 參數所指向之 WSABUF 結構的 len 成員一開始包含應用程式為 WSABUF 結構 buf 成員配置的緩衝區長度。 lpCalleeData 參數所指向之 WSABUF 結構的 len 成員將會在未傳回用戶數據時設定為零。當連線作業完成時 ，lpCalleeData 資訊將會有效。針對封鎖套接字，當 WSAConnect 函式傳回時，聯機作業就會完成。對於非封鎖套接字，完成會在發生FD_CONNECT通知之後。如果 lpCalleeData 為 NULL，則不會傳回任何用戶數據。用戶數據的確切格式專屬於套接字所屬的位址系列。

在連線時，應用程式可以使用 lpSQOS 和 lpGQOS 參數來覆寫透過 WSAIoctl 透過 WSAIoctl 針對套接字所做的任何先前服務質量規格，並搭配 SIO_SET_QOS 或 SIO_SET_GROUP_QOS opcode。

lpSQOS 參數會指定套接字的FLOWSPEC 結構，每個方向各有一個，後面接著任何其他提供者特定參數。如果一般相關聯的傳輸提供者或特定類型的套接字無法接受服務品質要求，則會傳回錯誤，如下列所示。針對任何單向套接字，將會分別忽略傳送或接收流程規格值。如果未指定提供者特定的參數，則 lpCalleeData 參數所指向之 WSABUF 結構的 buf 和 len 成員應該分別設定為 NULL 和零。 lpSQOS 參數的 NULL 值表示沒有應用程式提供的服務品質。

保留給未來搭配套接字群組 使用 lpGQOS 指定套接字 (群組的 FLOWSPEC 結構，如果適用) ，則每個方向各有一個，後面接著任何其他提供者特定參數。如果未指定提供者特定的參數，則 lpCalleeData 參數所指向之 WSABUF 結構的 buf 和 len 成員應該分別設定為 NULL 和零。 lpGQOS 的 NULL 值表示沒有應用程式提供的群組服務品質。如果 s 不是套接字群組的建立者，則會忽略此參數。

當連線的套接字因為任何原因而關閉時，應該捨棄並重新建立它們。假設因為連線套接字上任何原因而發生問題時，應用程式必須捨棄並重新建立所需的套接字，才能返回穩定點。

注意發出封鎖的 Winsock 呼叫，例如 WSAConnect 時，Winsock 可能需要等候網路事件，才能完成呼叫。 Winsock 會在這種情況中執行可警示的等候，而異步過程調用 (APC) 排程在同一個線程上，可能會中斷。在 APC 內發出另一個封鎖 Winsock 呼叫，中斷相同線程上持續封鎖 Winsock 呼叫會導致未定義的行為，而且永遠不會由 Winsock 客戶端嘗試。

Windows Phone 8：Windows Phone Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援此函式。

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

規格需求

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