Share via

SIO_IDEAL_SEND_BACKLOG_CHANGE コントロール コード

  • [アーティクル]

説明

SIO_IDEAL_SEND_BACKLOG_CHANGE 制御コードは、接続の理想的な送信バックログ (ISB) 値が変更されたときにアプリケーションに通知します。

この操作を実行するには、次のパラメーターを指定して 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

出力バッファーのサイズ (バイト単位)。 このパラメーターは 0 に設定する必要があります。

lpcbBytesReturned

出力バッファーに格納されているデータのサイズ (バイト単位) を受け取る変数へのポインター。 この返されるパラメーターは、出力がないため、この操作の DWORD 値 0 を指します。

lpvOverlapped

WSAOVERLAPPED 構造体へのポインター。

重複する属性なしでソケット s が作成された場合、 lpOverlapped パラメーターは無視されます。

重複する属性で s が開き、lpOverlapped パラメーターが NULL でない場合、操作は重複 (非同期) 操作として実行されます。 この場合、lpOverlapped パラメーターは有効な WSAOVERLAPPED 構造体を指している必要があります。

重複する操作の場合、WSAIoctl または WSPIoctl 関数はすぐに戻り、操作が完了すると適切な完了メソッドが通知されます。 それ以外の場合、操作が完了するかエラーが発生するまで関数は戻りません。

lpCompletionRoutine

型: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

操作が完了したときに呼び出される完了ルーチンへのポインター (重複していないソケットの場合は無視されます)。

lpThreadId

WPUQueueApc への後続の呼び出しでプロバイダーによって使用される WSATHREADID 構造体へのポインター。 プロバイダーは、WPUQueueApc 関数が戻るまで、参照先の WSATHREADID 構造体 (同上へのポインターではない) を格納する必要があります。

注 このパラメーターは、 WSPIoctl 関数にのみ適用されます。

lpErrno

エラー コードへのポインター。

注 このパラメーターは、 WSPIoctl 関数にのみ適用されます。

戻り値

操作が正常に完了すると、 WSAIoctl または WSPIoctl 関数は 0 を返します。

操作が失敗した場合、または保留中の場合、WSAIoctl または WSPIoctl 関数は SOCKET_ERROR を返します。 拡張エラー情報を取得するには、WSAGetLastError を呼び出します。

エラー コード 意味
WSA_IO_PENDING 重複する操作が正常に開始され、完了は後で示されます。
WSA_OPERATION_ABORTED ソケットのクローズまたは SIO_FLUSH IOCTL コマンドの実行により、重複する操作が取り消されました。
WSAEFAULT lpOverlapped パラメーターまたは lpCompletionRoutine パラメーターは、ユーザー・アドレス・スペースの有効な部分に完全には含まれていません。
WSAEINPROGRESS この関数は、コールバックが進行中のときに呼び出されます。
WSAEINTR ブロック操作が中断されました。
WSAEINVAL dwIoControlCode パラメーターが有効なコマンドではないか、指定された入力パラメーターが受け入れられないか、指定されたソケットの型にコマンドが適用されません。 cbOutBuffer パラメーターが 0 でない場合、このエラーが返されます。
WSAENETDOWN ネットワーク サブシステムが失敗しました。
WSAENOPROTOOPT ソケット オプションは、指定されたプロトコルではサポートされていません。
WSAENOTCONN ソケット s が接続されていません。
WSAENOTSOCK 記述子 s はソケットではありません。
WSAEOPNOTSUPP 指定された IOCTL コマンドはサポートされていません。 このエラーは、SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL がトランスポート プロバイダーでサポートされていない場合に返されます。 このエラーは、SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL の使用 がデータグラム ソケットで行われた場合にも返されます。

解説

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL は、Windows Server 2008、Windows Vista Service Pack 1 (SP1)、およびそれ以降のバージョンのオペレーティング システムでサポートされています。

Windows ソケットを使用して TCP 接続経由でデータを送信する場合は、最高のスループットを実現するために、TCP で十分な量のデータを未処理 (送信済みだがまだ確認されていない) にしておくことが重要です。 TCP 接続に最適なスループットを実現するために未処理のデータ量の理想的な値は、理想的な送信バックログ (ISB) サイズと呼ばれます。 ISB 値は、TCP 接続と受信側のアドバタイズされた受信ウィンドウ (および一部はネットワーク内の輻輳の量) の帯域幅遅延積の関数です。

接続ごとの ISB 値は、Windows Server 2008、Windows Vista SP1、およびそれ以降のバージョンのオペレーティング システムの TCP プロトコル実装から使用できます。 SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL は、アプリケーションが接続に対して ISB 値が動的に変化したときに通知を取得するために使用できます。

Windows Server 2008、Windows Vista SP1、およびそれ以降のバージョンのオペレーティング システムでは、接続状態のストリーム指向ソケットで SIO_IDEAL_SEND_BACKLOG_CHANGE および SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL がサポートされています。

TCP 接続の ISB 値の範囲は、理論的には 0 から最大 16 メガバイトまでさまざまです。

高帯域幅遅延製品接続よりも優れたスループットを実現するための 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 を発行できますが、ISB 値が変更されるまで IOCTL は単にブロックまたは保留されます。

lpOverlapped パラメーターと lpCompletionRoutine パラメーターの両方 が NULL の場合、この関数のソケットは重複しないソケットとして扱われます。 重複していないソケットの場合、 lpOverlapped パラメーターと lpCompletionRoutine パラメーターは無視されますが、ソケット s がブロック モードの場合、関数がブロックできる点が異なります。 ソケット s が非ブロッキング モードの場合、この特定の IOCTL は非ブロッキング モードをサポートしていないため、この関数は引き続きブロックされます。

重複するソケットの場合、すぐに完了できない操作が開始され、完了は後で示されます。

サービス プロバイダーの実装によっては、IOCTL が無期限にブロックされる場合があります。 アプリケーションが WSAIoctl または WSPIoctl 関数呼び出しでのブロックを許容できない場合は、特にブロックする可能性が高い IOCTL に対して重複した I/O が推奨されます。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL は通知を提供し、ISB 値が変更されるまでブロックまたは保留されることが期待されます。 そのため、lpOverlapped パラメーターを有効な WSAOVERLAPPED 構造体に設定して非同期的に呼び出されるのが一般的です。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL は、次の場合に WSAEINTR または WSA_OPERATION_ABORTED で失敗する可能性があります:

  • TCP 接続は、送信方向に正常に切断されます。 これは、パラメーターを SD_SEND に設定したシャットダウン関数の呼び出し、DisconnectEx 関数の 呼び出し、 dwFlags パラメーターを TF_DISCONNECT または TF_REUSE に 設定した TransmitFile または TransmitPackets 関数の呼び出しの結果として発生する可能性があります。
  • TCP 接続がリセットまたは中止されました。
  • アプリケーションは、既にペンド通知要求がある場合に、SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL を発行します。 一度に許可される保留中の SIO_IDEAL_SEND_BACKLOG_CHANGE 要求は 1 つだけです。
  • 要求は I/O マネージャーによって取り消されます。
  • ソケットが閉じています。

これらの IOCTL の 2 つのインライン ラッパー関数は、Ws2tcpip.h ヘッダー ファイルで 定義されています。 これらのインライン関数は、SIO_IDEAL_SEND_BACKLOG_CHANGE と SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL を直接使用する代わりに使用 することをお勧めします。

SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL の インライン ラッパー関数は、idealsendbacklognotify 関数です。

SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL の インライン ラッパー関数は、idealsendbacklogquery 関数です。

関連項目

SIO_IDEAL_SEND_BACKLOG_QUERY

socket

WSAGetLastError

WSAGetOverlappedResult

WSAIoctl

WSAOVERLAPPED

WSASocketA

WSASocketW