SIO_IDEAL_SEND_BACKLOG_QUERY控制項程式碼

發行項
06/13/2023

描述

SIO_IDEAL_SEND_BACKLOG_QUERY控制程式代碼會擷取基礎連線的理想傳送待辦專案 (ISB) 值。

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_QUERY, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY 。

lpvInBuffer

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

cbInBuffer

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

lpvOutBuffer

輸出緩衝區的指標。如果lpOverlapped和lpCompletionRoutine參數為Null，此參數應該指向ULONG資料類型。

cbOutBuffer

輸出緩衝區的大小，以位元組為單位。此參數至少必須是 ULONG 資料類型的大小。

lmicrosoftBytesReturned

變數的指標，接收儲存在輸出緩衝區中的資料大小，以位元組為單位。

如果輸出緩衝區太小，則呼叫會失敗， WSAGetLastError 會傳回 WSAEINVAL，而 lBytesReturned 參數會指向 零的 DWORD 值。

如果lpOverlapped為Null，則成功呼叫時所傳回之lBytesReturned參數所指向的DWORD值不能為零。

如果重迭通訊端的 lpOverlapped 參數不是 Null ，則無法立即完成的作業將會起始，且稍後會指出完成。由傳回之lBytesReturned參數所指向的DWORD值可能是零，因為儲存的資料大小在重迭作業完成之前無法判斷。當作業完成完成時，可以擷取適當的完成方法時，擷取最終完成狀態。

lpvOverlapped

WSAOVERLAPPED結構的指標。

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

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

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

lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

當作業完成時呼叫的完成常式指標， (忽略非重迭通訊端) 。

lpThreadId

提供者後續呼叫WPUQueueApc時要使用的WSATHREADID結構的指標。提供者應該儲存參考的 WSATHREADID 結構， (直到 WPUQueueApc 函式傳回之後，才儲存相同) 的指標。

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

lpErrno

錯誤碼的指標。

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

傳回值

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

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

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

備註

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

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

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

在 Windows Server 2008 上，Windows Vista SP1 和更新版本的作業系統支援 SIO_IDEAL_SEND_BACKLOG_CHANGE 和 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL，且資料流程導向通訊端處於線上狀態。

TCP 連線的 ISB 值範圍理論上可能會從 0 變更為 16 MB。

SIO_IDEAL_SEND_BACKLOG_CHANGE和SIO_IDEAL_SEND_BACKLOG_QUERY IOCTLs 的一般用法是以應用程式所使用的傳送方法為基礎。討論兩個常見案例。

一次執行一個封鎖或非封鎖傳送要求的應用程式，通常會依賴 Winsock 的內部傳送緩衝來達到良好的輸送量。指定連接的傳送緩衝區限制是由 SO_SNDBUF 通訊端選項所控制。對於封鎖和非封鎖傳送方法，傳送緩衝區限制會決定 TCP 中未處理的資料量。如果連線的 ISB 值大於傳送緩衝區限制，則連線上達成的輸送量將不會是最佳。為了達到更好的輸送量，應用程式可以根據 ISB 查詢的結果來設定傳送緩衝區限制，因為 ISB 變更通知發生在連線上。

對於使用重迭傳送方法與多個未處理傳送要求的應用程式，TCP 中保留未處理的資料量取決於 Winsock 中的傳送緩衝區限制，以及未處理重迭傳送要求中包含的資料總數。在此情況下，應用程式應該使用 ISB 值來判斷應保留的未處理傳送要求數目，以及每個傳送要求的資料大小應該是什麼。在理想情況下，應用程式應該嘗試保留下列方程式：

ISB value == send buffer limit + (number of simultaneous overlapped send requests * data length per send request)

請注意，使用上述方式透過 TCP 通訊端的 ISB IOCTL，可能會導致記憶體使用量增加，以交換高頻寬延遲產品連線上的輸送量。 Windows 中的 TCP 實作會視需要根據整體系統記憶體使用量來節流 ISB 值。

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

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

SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 不太可能封鎖，因此通常會與設定為Null的lpOverlapped和lpCompletionRoutine參數同步呼叫。

SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 在下列情況下，WSAEINTR或WSA_OPERATION_ABORTED失敗：

TCP 連線會以傳送方向正常中斷連線。這可能會因為呼叫 shutdown 函式而發生，其中參數設定為 SD_SEND、 DisconnectEx 函式的呼叫，或對 TransmitFile 或 TransmitPackets 函式的呼叫，並將 dwFlags 參數設定為 TF_DISCONNECT 或 TF_REUSE。 TCP 連線已重設或中止。 I/O 管理員會取消要求。

這些 IOCTL 的兩個內嵌包裝函式定義于 Ws2tcpip.h 標頭檔中。建議使用這些內嵌函式，而不是直接使用 SIO_IDEAL_SEND_BACKLOG_CHANGE 和 SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL 的內嵌包裝函式是理想的backlognotify 函式。

SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 的內嵌包裝函式是理想的sendbacklogquery函式。

Windows 7 和 Windows Server 2008 R2 上已新增 TCP 的動態傳送緩衝。根據預設，除非應用程式在資料流程通訊端上設定 SO_SNDBUF 通訊端選項，否則會啟用 TCP 的動態傳送緩衝。

建議使用 netsh 方法來查詢或設定 TCP 的動態傳送緩衝。

您可以使用下列命令來擷取 TCP 動態傳送緩衝的目前值：

netsh winsock show autotuning

您可以使用下列命令停用 TCP 的動態傳送緩衝：

netsh winsock set autotuning off

您可以使用下列命令來啟用 TCP 的動態傳送緩衝：

netsh winsock set autotuning on

雖然不建議使用，但您可以將下列登錄值設定為零，從應用程式停用動態傳送緩衝：