SIO_IDEAL_SEND_BACKLOG_CHANGE控制項程式碼

發行項
10/11/2023

描述

當 連線的理想傳送待辦專案（ISB）值變更時，SIO_IDEAL_SEND_BACKLOG_CHANGE 控制項程式碼會通知應用程式。

若要執行這項作業，請使用下列參數呼叫 WSAIoctl 或 WSPIoctl 函式。

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

參數

s

識別通訊端的描述項。

dwIoControlCode

作業的控制項程式碼。針對此作業使用 SIO_IDEAL_SEND_BACKLOG_CHANGE 。

lpvInBuffer

輸入緩衝區的指標。這個作業未使用此參數。

cbInBuffer

輸入緩衝區的大小，以位元組為單位。這個作業未使用此參數。

lpvOutBuffer

輸出緩衝區的指標。這個作業未使用此參數。

cbOutBuffer

輸出緩衝區的大小，以位元組為單位。此參數必須設定為零。

l pbReturned

變數的指標，這個變數會接收輸出緩衝區中所儲存資料的大小，以位元組為單位。這個傳回的參數會指向 此作業的 DWORD 值零，因為沒有輸出。

lpvOverlapped

WSAOVERLAPPED 結構的指標。

如果未建立通訊端，但未重迭屬性， 則會忽略 lpOverlapped 參數。

如果 已使用重迭屬性開啟 s ，且 lpOverlapped 參數不是 Null ，則作業會以重迭的（非同步）作業執行。在此情況下，lpOverlapped 參數必須指向有效的 WSAOVERLAPPED 結構。

針對重迭的作業， WSAIoctl 或 WSPIoctl 函式會立即傳回，並在作業完成時發出適當的完成方法訊號。否則，在作業完成或發生錯誤之前，函式不會傳回。

lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

完成作業完成時呼叫的完成常式指標（針對非重迭通訊端忽略）。

lpThreadId

提供者後續呼叫 WPUQueueApc 時要使用的 WSATHREADID 結構的指標。 提供者應該在 WPUQueueApc 函式傳回之後 ，才儲存參考的 WSATHREADID 結構（而非相同指標）。

注意此參數僅適用于 WSPIoctl 函 式。

lpErrno

錯誤碼的指標。

注意此參數僅適用于 WSPIoctl 函 式。

傳回值

如果作業順利完成， WSAIoctl 或 WSPIoctl 函式會傳回零。

如果作業失敗或擱置中 ，WSAIoctl 或 WSPIoctl 函式會傳回SOCKET_ERROR。若要取得擴充的錯誤資訊，請呼叫 WSAGetLastError 。

錯誤碼	意義
WSA_IO_PENDING	已成功起始重迭的作業，稍後將會指出完成。
WSA_OPERATION_ABORTED	由於通訊端關閉或執行 SIO_FLUSH IOCTL 命令，所以已取消重迭的作業。
WSAEFAULT	lpOverlapped 或 lpCompletionRoutine 參數不會完全包含在使用者位址空間的有效部分中。
WSAEINPROGRESS	當回呼正在進行時，會叫用函式。
WSAEINTR	封鎖作業中斷。
WSAEINVAL	dwIoControlCode 參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的通訊端類型。如果 cbOutBuffer 參數不是零，則會傳回此錯誤。
WSAENETDOWN	網路子系統失敗。
WSAENOPROTOOPT	指定的通訊協定不支援通訊端選項。
WSAENOTCONN	通訊端未連線。
WSAENOTSOCK	描述元 s 不是通訊端。
WSAEOPNOTSUPP	不支援指定的 IOCTL 命令。如果傳輸提供者不支援SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL，則會傳回此錯誤。嘗試在資料包通訊端上使用 IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE 時，也會傳回此錯誤。

備註

Windows Server 2008、Windows Vista Service Pack 1 （SP1）和更新版本的作業系統都支援SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL。

使用 Windows 通訊端透過 TCP 連線傳送資料時，請務必在 TCP 中保留足夠的未處理資料量（已傳送但尚未認可），才能達到最高的輸送量。達到 TCP 連線最佳輸送量之未處理資料量的理想值，稱為理想的傳送待辦專案（ISB）大小。 ISB 值是 TCP 連線的頻寬延遲乘積和接收者公告接收視窗的函式（部分是網路擁堵量）。

每個連線的 ISB 值可從 Windows Server 2008、Windows Vista SP1 和更新版本的作業系統中的 TCP 通訊協定實作取得。當 ISB 值動態變更連線時，應用程式可以使用SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 來取得通知。

在 Windows Server 2008 上，Windows Vista SP1 和更新版本的作業系統支援 SIO_IDEAL_SEND_BACKLOG_CHANGE 和 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL，這些通訊端處於線上狀態。

TCP 連線的 ISB 值範圍理論上可能從 0 到最多 16 MB 不等。

如需 ISB 機制的一般使用方式，請參閱 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 參考頁面，以透過高頻寬延遲產品連線達到更好的輸送量。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 只能在處於線上狀態的資料流程通訊端上。否則 WSAIoctl 或 WSPIoctl 函式會失敗，WSAENOTCONN 。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 不會使用輸入或輸出緩衝區和畫筆或區塊，直到基礎連線發生 ISB 變更為止。完成此 IOCTL 時，Winsock 應用程式可以使用 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 來擷取連線上的新 ISB 值。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 不支援非封鎖模式。應用程式允許在非封鎖通訊端上發出此 IOCTL，但 IOCTL 只會封鎖或畫上，直到 ISB 值變更為止。

如果 lpOverlapped 和 lpCompletionRoutine 參數都是 Null，則此函式中的通訊端會被視為非重迭的通訊端。若為非重迭的通訊端， 則會忽略 lpOverlapped 和 lpCompletionRoutine 參數，但函式可以在通訊端處於封鎖模式時封鎖。如果通訊端處於非封鎖模式，此函式仍會封鎖，因為這個特定的 IOCTL 不支援非封鎖模式。

對於重迭的通訊端，無法立即完成的作業將會起始，稍後將會指出完成。

根據服務提供者的實作而定，任何 IOCTL 都可能會無限期地封鎖。如果應用程式無法容許在 WSAIoctl 或 WSPIoctl 函式呼叫中 封鎖，則特別可能封鎖的 IOCTLs 會建議重迭的 I/O。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 會提供通知，並預期會封鎖或畫上，直到 ISB 值變更為止。因此，通常會以非同步方式呼叫，並將 lpOverlapped 參數設定為有效的 WSAOVERLAPPED 結構。

在 下列情況下，IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE WSAEINTR 或 WSA_OPERATION_ABORTED 可能會失敗 ：

TCP 連線在傳送方向中會正常中斷連線。這可能會因為呼叫 shutdown 函式而發生，參數設定為 SD_SEND、DisconnectEx 函式的呼叫，或呼叫 TransmitFile 或 TransmitPackets 函 式，並將 dwFlags 參數設定為 TF_DISCONNECT 或 TF_REUSE 。
TCP 連線已重設或中止。
當已經有畫筆通知要求時，應用程式會發出 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL。一次只允許一個畫 筆SIO_IDEAL_SEND_BACKLOG_CHANGE 要求。
I/O 管理員會取消要求。
通訊端已關閉。