LPWSPCONNECT 回呼函式 (ws2spi.h)
LPWSPConnect 函式會建立對等連線、交換連接數據，並根據提供的流程規格指定所需的服務品質。
語法
LPWSPCONNECT Lpwspconnect;
int Lpwspconnect(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen,
[in] LPWSABUF lpCallerData,
[out] LPWSABUF lpCalleeData,
[in] LPQOS lpSQOS,
[in] LPQOS lpGQOS,
[out] LPINT lpErrno
)
{...}
參數
[in] s
識別未連接套接字的描述項。
[in] name
要連接sockaddr中套接字的對等名稱。
[in] namelen
名稱的長度，以位元組為單位。
[in] lpCallerData
線上建立期間要傳送至對等的用戶數據指標。
[out] lpCalleeData
緩衝區的指標，您可以在連接建立期間複製從對等接收的任何用戶數據。
[in] lpSQOS
套接字 的流程規格指標，每個方向各一個。
[in] lpGQOS
保留的。
[out] lpErrno
錯誤碼的指標。
傳回值
如果沒有發生錯誤， LPWSPConnect 會傳回零。 否則，它會傳回SOCKET_ERROR，而且 lpErrno 中提供特定的錯誤碼。
在封鎖套接字上，傳回值表示連線嘗試成功或失敗。 如果傳回錯誤碼指出連線嘗試失敗 (亦即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) Winsock SPI 用戶端可以針對相同的套接字再次呼叫 LPWSPConnect 。
| 錯誤碼 | 意義 |
|---|---|
| 網路子系統失敗。 | |
| 套接字的本機位址已在使用中，且套接字未標示為允許使用 SO_REUSEADDR 重複使用位址。 這個錯誤通常會在系結時發生，但如果系結至涉及ADDR_ANY) 的部分通配符地址，而且此函式必須在此函式時認可特定 (位址，則可能會延遲到此函式。 | |
| (封鎖) 呼叫已透過 LPWSPCancelBlockingCall 取消。 | |
| 封鎖 Winsock 呼叫正在進行中，或服務提供者仍在處理回呼函式。 | |
|
指定的套接字上正在進行非封鎖 LPWSPConnect 呼叫。 為了保留回溯相容性，此錯誤會回報為 WSAEINVAL 至連結至 Winsock.dll 或 Wsock32.dll 的 Windows Sockets 1.1 應用程式。 |
|
| 例如，遠端位址不是有效的位址 (，ADDR_ANY) 。 | |
| 指定之系列中的位址無法用於此通訊端。 | |
| 嘗試連線遭到拒絕。 | |
| 名稱或 namelen 參數不是使用者位址空間的有效部分、namelen 參數太小、lpCalleeData、lpSQOS 和 lpGQOS 的緩衝區長度太小，或 lpCallerData 的緩衝區長度太大。 | |
| 參數 s 是接聽套接字。 | |
| 套接字已連線 (連線導向套接字) 。 | |
| 此時無法透過此主機連接網路。 | |
| 沒有可用的緩衝區空間。 套接字無法連接。 | |
| 描述項不是套接字。 | |
| 無法滿足 lpSQOS 中指定的流程規格。 | |
| 服務提供者不支援 lpCallerData 擴增。 | |
| 嘗試連線逾時，而不需建立連線。 | |
| 套接字標示為非封鎖，且無法立即完成連線。 使用 **WSPSelect** 函式進行連線時，可以使用 LPWSPSelect 函式來選取套接字以進行寫入。 | |
| 嘗試將數據報套接字連線到廣播位址失敗，因為未啟用 WSPSetSockOpt SO_BROADCAST。 |
備註
此函式可用來建立與指定目的地的連線，以及執行一些其他連接時間發生的輔助作業。 如果套接字 s 為未系結，則會將唯一值指派給系統的區域關聯，且套接字會標示為系結。
例如，針對連線導向套接字 (類型SOCK_STREAM) ，使用 名稱 (套接字命名空間中的位址，對指定的主機起始作用中連線。 如需詳細描述，請參閱 LPWSPBind。 當此呼叫順利完成時，套接字已準備好傳送和接收數據。 如果 名稱 結構的地址成員全部為零， LPWSPConnect 會傳回錯誤 WSAEADDRNOTAVAIL。 任何嘗試重新連線使用中的連線都會失敗，並出現錯誤碼 WSAEISCONN。
針對連線導向的非封鎖套接字，通常無法立即完成連線。 在這種情況下，此函式會傳回錯誤 WSAEWOULDBLOCK ，但作業會繼續進行。 當成功或失敗結果變成已知時，可能會以數種方式之一回報，視用戶端註冊通知的方式而定。 如果用戶端使用 LPWSPSelect， 則會在 writefds 集合中回報成功， 並在 exceptfds 集合中回報失敗。 如果用戶端使用 LPWSPAsyncSelect 或 LPWSPEventSelect，則會以FD_CONNECT宣告通知，而與FD_CONNECT相關聯的錯誤碼表示成功或失敗的特定原因。
例如，針對無連線套接字 (輸入 SOCK_DGRAM) ，LPWSPConnect 所執行的作業是建立預設目的地位址，讓套接字可以搭配後續連線導向的傳送和接收作業使用， (LPWSPSend、 LPWSPRecv) 。 從指定之目的地位址以外的位址接收的任何數據報都會被捨棄。 如果名稱結構的地址成員全部為零，套接字將會中斷連線， 預設遠端位址將會不確定，因此 LPWSPSend 和 LPWSPRecv 呼叫會傳回錯誤碼 WSAENOTCONN。 不過，仍然可以使用 LPWSPSendTo 和 LPWSPRecvFrom 。 只要再次呼叫 LPWSPConnect 即可變更預設目的地，即使套接字已連線也一樣。 如果 名稱 與先前 的 LPWSPConnect 不同，則會捨棄任何排入回條的數據報。
對於無連線套接字， name 可以指出任何有效的位址，包括廣播位址。 不過，若要連線到廣播位址，套接字必須啟用 WSPSetSockOpt SO_BROADCAST。 否則 ，LPWSPConnect 將會失敗，並出現錯誤碼 WSAEACCES。
在無連線套接字上，無法交換使用者對用戶數據，而且會以無訊息方式忽略對應的參數。
Winsock SPI 用戶端負責由它指定的任何參數，直接或間接配置指向的任何記憶體空間。
lpCallerData 是值參數，其中包含要連同連線要求一起傳送的任何用戶數據。 如果 lpCallerData 為 null，則不會將用戶數據傳遞至對等。 lpCalleeData 是結果參數，會參考從對等傳回的任何用戶數據作為連線建立的一部分。 lpCalleeData-len> 一開始包含 Winsock SPI 用戶端所配置的緩衝區長度，並由 lpCalleeData-buf> 指向。 如果未傳回任何用戶數據，lpCalleeData-len> 將會設定為零。 當連線作業完成時 ，lpCalleeData 資訊將會有效。 針對封鎖套接字，這會是 當 LPWSPConnect 函式傳回時。 針對非封鎖套接字，這會在發生FD_CONNECT通知之後。 如果 lpCalleeData 為 null，則不會傳回任何用戶數據。 用戶數據的確切格式專屬於套接字所屬的位址系列，以及/或涉及的應用程式。
在連線時， Winsock SPI 用戶端可以使用 lpSQOS 參數，透過 LPWSPIoctl 覆寫透過 LPWSPIoctl 針對套接字所做的任何先前 QoS 規格，搭配 SIO_SET_QOS opcode。
lpSQOS 會指定套接字的流程規格，每個方向各指定一個，後面接著任何其他提供者特定的參數。 如果一般相關聯的傳輸提供者或特定類型的套接字無法接受 QoS 要求，則會傳回錯誤，如下所示。 對於任何單向套接字，將會分別忽略傳送或接收流程規格值。 如果未提供提供者特定的參數，則 lpSQOS-ProviderSpecific> 的 buf 和 len 成員應該分別設定為 null 和零。 lpSQOS 的 Null 值表示沒有應用程式提供服務品質。
注意
當連線的套接字中斷 (也就是說，基於任何原因而關閉) 時，應該捨棄並重新建立它們。 最安全的方式是假設當連線套接字上基於任何原因而發生包裝時，Winsock SPI 客戶端必須捨棄並重新建立所需的套接字，才能回到穩定點。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 標頭 | ws2spi.h |