shutdown 函式 (winsock.h)

發行項
03/13/2024

關機函式會停用套接字上的傳送或接收。

語法

int shutdown(
  [in] SOCKET s,
  [in] int    how
);

參數

[in] s

識別套接字的描述項。

[in] how

描述不再允許何種類型的作業的旗標。此旗標的可能值列在 Winsock2.h 頭檔中。

值	意義
SD_RECEIVE 0	關機接收作業。
SD_SEND 1	關機傳送作業。
SD_BOTH 2	關閉傳送和接收作業。

傳回值

如果沒有發生錯誤，關機會傳回零。否則，會傳回SOCKET_ERROR的值，而且可以呼叫 WSAGetLastError 來擷取特定的錯誤碼。

錯誤碼	意義
WSAECONNABORTED	此虛擬電路由於逾時或其他錯誤而終止。此通訊端無法再使用，應用程式應予以關閉。此錯誤僅適用於連線導向套接字。
WSAECONNRESET	執行硬式或失敗關閉的遠端部分已重設此虛擬電路。此通訊端無法再使用，應用程式應予以關閉。此錯誤僅適用於連線導向套接字。
WSAEINPROGRESS	封鎖的 Windows Sockets 1.1 呼叫正在進行中，或者服務提供者仍在處理回呼函式。
WSAEINVAL	參數無效的方式，或與套接字類型不一致。例如，SD_SEND與UNI_RECV套接字類型搭配使用。
WSAENETDOWN	網路子系統失敗。
WSAENOTCONN	未連接此通訊端。此錯誤僅適用於連線導向套接字。
WSAENOTSOCK	注意描述項不是套接字。
WSANOTINITIALISED	使用此函式之前，必須先進行成功的 WSAStartup 呼叫。

備註

關機函式用於所有類型的套接字，以停用接收、傳輸或兩者。

如果 參數如何 SD_RECEIVE，則不允許對套接字上 recv 函式的後續呼叫。這不會影響較低的通訊協定層。針對 TCP 套接字，如果套接字上仍有數據排入佇列等候接收，或數據後續送達，則會重設連線，因為無法將數據傳遞給使用者。針對UDP套接字，會接受並排入傳入的數據報。在此情況下，不會產生ICMP錯誤封包。

如果 參數如何 SD_SEND，則不允許對 send 函式的後續呼叫。針對 TCP 套接字，在接收者傳送和認可所有數據之後，將會傳送 FIN。

設定如何 SD_BOTH停用傳送和接收，如上所述。

關機函式不會關閉套接字。在叫用 closesocket 之前，將不會釋放任何附加至套接字的資源。

為了確保在關閉之前，所有數據都會在連線的套接字上傳送和接收，應用程式應該先使用關機來關閉連線，再呼叫 closesocket。一個等候遠端端已傳送所有數據並起始正常中斷連線的通知的方法，請使用 WSAEventSelect 函式，如下所示：

呼叫 WSAEventSelect 以註冊FD_CLOSE通知。
使用 how=SD_SEND 呼叫關機。
收到FD_CLOSE時，請呼叫 recv 或 WSARecv ，直到函式完成並指出已收到零個字節為止。如果傳回SOCKET_ERROR，則無法正常中斷連線。
呼叫 closesocket。

另一個等候遠端端已傳送所有數據並起始正常中斷連線的通知的方法，使用重疊的接收呼叫如下：

使用 how=SD_SEND 呼叫關機。
呼叫 recv 或 WSARecv ，直到函式成功完成，並指出已收到零個字節。如果傳回SOCKET_ERROR，則無法正常中斷連線。
呼叫 closesocket。

注意不論套接字上的SO_LINGER設定為何，關機函式都不會封鎖。

如需詳細資訊，請參閱正常關機、Linger 選項和套接字關閉一節。

呼叫關機函式以停用傳送、接收或兩者之後，就沒有方法可以重新啟用現有套接字連線的傳送或接收。

應用程式不應該依賴在關閉套接字之後重複使用套接字。特別是，Windows Sockets 提供者不需要支援在已關閉的套接字上使用連線。

如果應用程式想要重複使用套接字，則應該使用 dwFlags 參數設定為 TF_REUSE_SOCKET 來呼叫 DisconnectEx 函式，以關閉套接字上的連線，並準備要重複使用的套接字句柄。 當 DisconnectEx 要求完成時，套接字句柄可以傳遞至 AcceptEx 或 ConnectEx 函式。

如果應用程式想要重複使用套接字，可以使用設定為 TF_DISCONNECT 的 dwFlags 參數來呼叫 TransmitFile 或 TransmitPackets 函式，並在所有數據排入佇列以供傳輸後TF_REUSE_SOCKET中斷連線，並準備要重複使用的套接字句柄。 當 TransmitFile 要求完成時，套接字句柄可以傳遞至先前用來建立連接的函式呼叫，例如 AcceptEx 或 ConnectEx。 當 TransmitPackets 函式完成時，套接字句柄可以傳遞至 AcceptEx 函式。

注意套接字層級中斷連線受限於基礎傳輸的行為。例如，TCP 套接字可能受限於 TCP TIME_WAIT狀態，導致 DisconnectEx、 TransmitFile 或 TransmitPackets 呼叫延遲。

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

ATM 的注意事項

使用異步傳輸模式 (ATM) 和 Windows 套接字 2 時，連線終止有一個重要問題。如需這些重要考慮的詳細資訊，請參閱 closesocket 函式參考一節中標題為 ATM 的附註一節。

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

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

規格需求

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