WSAConnect 函式 (winsock2.h)
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 來指出對線上活動感興趣，當連線作業完成 (或未) 時，相關聯的事件物件將會發出訊號。
如果傳回錯誤碼指出連線嘗試失敗 (亦即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) 應用程式可以針對相同的通訊端再次呼叫 WSAConnect 。
| 錯誤碼 | 意義 |
|---|---|
| 使用這個函式之前，必須先進行成功的 WSAStartup 呼叫。 | |
| 網路子系統失敗。 | |
| 通訊端的本機位址已在使用中，且通訊端未標示為允許與SO_REUSEADDR重複使用位址。 此錯誤通常會在執行 系結期間發生，但如果 系結 函式在涉及ADDR_ANY) 的部分萬用字元位址上運作，而且此函式必須在此函式時「認可」特定 (位址，則可能會延遲到此函式。 | |
| (封鎖) Windows Socket 1.1 呼叫已透過 WSACancelBlockingCall取消。 | |
| 封鎖的 Windows Sockets 1.1 呼叫正在進行中，或服務提供者仍在處理回呼函式。 | |
| 在指定的通訊端上正在進行非封鎖 連線 或 WSAConnect 呼叫。 | |
| 遠端位址不是 (的有效位址，例如ADDR_ANY) 。 | |
| 指定之系列中的位址無法用於此通訊端。 | |
| 嘗試連線已遭到拒絕。 | |
| name或namelen參數不是使用者位址空間的有效部分、namelen參數太小、lpCalleeData、lpSQOS和lpGQOS的緩衝區長度太小，或lpCallerData的緩衝區長度太大。 | |
| 參數 s 是接聽通訊端，或指定的目的地位址與通訊端所屬之受限制群組的位址不一致，或 lpGQOS 參數不是 Null。 | |
| 通訊端已 (連線導向通訊端) 。 | |
| 此時無法透過此主機連接網路。 | |
| 已嘗試對無法連接的主機進行通訊端作業。 | |
| 沒有可用的緩衝區空間。 通訊端無法連接。 | |
| 描述項不是通訊端。 | |
| 無法滿足lpSQOS和lpGQOS中指定的FLOWSPEC結構。 | |
| 服務提供者不支援 lpCallerData 參數。 | |
| 嘗試連線逾時，而不需建立連線。 | |
| 通訊端標示為非封鎖，且無法立即完成連線。 | |
| 嘗試將資料包通訊端連線到廣播位址失敗，因為 未啟用 setockopt SO_BROADCAST。 |
備註
WSAConnect函式可用來建立與指定目的地的連線，以及執行一些在連線時間發生的其他輔助作業。 如果通訊端 s是未系結的，系統就會將唯一值指派給本機關聯，而且通訊端會標示為系結。
針對以 Windows Vista 和更新版本為目標的應用程式，請考慮使用 WSAConnectByList 或 WSAConnectByName 函式，大幅簡化用戶端應用程式設計。
例如，針對連線導向通訊端 (類型SOCK_STREAM) ，使用 名稱 (通訊端命名空間中的位址來起始對外部主機的作用中連線;如需詳細描述，請參閱 系結) 。 當此呼叫成功完成時，通訊端便已準備好傳送/接收資料。 如果 名稱 結構的 address 參數全部為零， WSAConnect 會傳回錯誤 WSAEADDRNOTAVAIL。 任何嘗試重新連線使用中的連線都會失敗，並出現錯誤碼 WSAEISCONN。
例如，對於無連線通訊端 (類型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 和其他通訊協定。
如果 lpCallerData 為 Null，則不會將使用者資料傳遞給對等。 lpCalleeData是結果參數，其中包含從另一個通訊端傳回的任何使用者資料，作為WSABUF結構中建立連線的一部分。 lpCalleeData參數所指向之 WSABUF結構的len成員一開始包含應用程式為WSABUF結構buf成員配置的緩衝區長度。 如果尚未傳回任何使用者資料，lpCalleeData參數所指向之WSABUF結構的len成員將會設定為零。 連線作業完成時 ，lpCalleeData 資訊將會有效。 針對封鎖通訊端， 當 WSAConnect 函式傳回時，連線作業就會完成。 若為非封鎖通訊端，完成會在發生FD_CONNECT通知之後完成。 如果 lpCalleeData 為 Null，則不會傳回任何使用者資料。 使用者資料的確切格式專屬於通訊端所屬的位址系列。
在連線時，應用程式可以使用 lpSQOS 和 lpGQOS 參數，透過 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值表示沒有應用程式提供的群組服務品質。 如果 不是 通訊端群組的建立者，則會忽略此參數。
當連線的通訊端因為任何原因而關閉時，應該捨棄並重新建立它們。 最安全的方式是假設當專案因任何原因而在連線的通訊端上發生包裝時，應用程式必須捨棄並重新建立所需的通訊端，才能回到穩定點。
Windows 8.1和Windows Server 2012 R2：Windows 市集應用程式在 Windows 8.1、Windows Server 2012 R2 及更新版本上支援此功能。
規格需求
| 最低支援的用戶端 | Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | winsock2.h |
| 程式庫 | Ws2_32.lib |
| Dll | Ws2_32.dll |
另請參閱
意見反應
提交並檢視相關的意見反應