SIO_APPLY_TRANSPORT_SETTING コントロールコード

[アーティクル]
06/12/2023

説明

SIO_APPLY_TRANSPORT_SETTING制御コードは、1 つ以上のトランスポート設定をソケットに適用します。

この操作を実行するには、次のパラメーターを指定して WSAIoctl または WSPIoctl 関数を呼び出します。

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING を使用します。

lpvInBuffer

入力バッファーへのポインター。このパラメーターには、構造体の最初のメンバーが、適用されるトランスポート設定を決定する TRANSPORT_SETTING_ID 構造体である構造体へのポインターが含まれています。

cbInBuffer

入力バッファーのサイズ (バイト単位)。このパラメーターは、適用されるトランスポート設定によって異なります。

lpvOutBuffer

出力バッファーへのポインター。このパラメーターは、適用されるトランスポート設定によって異なります。

cbOutBuffer

出力バッファーのサイズ (バイト単位)。

lpcbBytesReturned

出力バッファーに格納されているデータのサイズ (バイト単位) を受け取る変数へのポインター。

出力バッファーが小さすぎる場合、呼び出しは失敗し、 WSAGetLastError はWSAEINVAL を返し、 lpcbBytesReturned パラメーターはDWORD 値 0 を指します。

lpOverlapped が NULL の場合、正常な呼び出しで返される lpcbBytesReturned パラメーターが指す DWORD 値を 0 にすることはできません。

重複するソケットに 対して lpOverlapped パラメーターが NULL でない場合、すぐには完了できない操作が開始され、完了は後で示されます。返される 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	重複した I/O 操作が進行中です。この値は、重複した操作が正常に開始され、完了が後で示される場合に返されます。
WSA_OPERATION_ABORTED	スレッドの終了またはアプリケーションの要求が原因で、I/O 操作が中止されました。このエラーは、ソケットのクローズまたは SIO_FLUSH IOCTL コマンドの実行により、重複した操作が取り消された場合に返されます。
WSAEFAULT	呼び出しでポインター引数を使用しようとしたときに、システムによって無効なポインターアドレスが検出されました。このエラーは、 lpvInBuffer、 lpvoutBuffer、 lpcbBytesReturned、 lpOverlapped または lpCompletionRoutine パラメーターが、ユーザーアドレス空間の有効な部分に完全には含まれていません。
WSAEINPROGRESS	現在、ブロック操作を実行中です。コールバックの実行中に関数が呼び出されると、このエラーが返されます。
WSAEINTR	WSACancelBlockingCall の呼び出しによってブロック操作が中断されました。このエラーは、ブロック操作が中断された場合に返されます。
WSAEINVAL	無効な引数が指定されました。このエラーは、 dwIoControlCode パラメーターが有効なコマンドではない場合、または指定された入力パラメーターが受け入れられない場合、または指定されたソケットの型にコマンドが適用されない場合に返されます。
WSAENETDOWN	ソケット操作によりネットワークの停止が検出されました。このエラーは、ネットワークサブシステムが失敗した場合に返されます。
WSAENOTSOCK	ソケットではない操作が試行されました。記述子 s がソケットでない場合、このエラーが返されます。
WSAEOPNOTSUPP	試行された操作は、参照されるオブジェクトの種類ではサポートされていません。このエラーは、指定された IOCTL コマンドがサポートされていない場合に返されます。このエラーは、 SIO_APPLY_TRANSPORT_SETTING IOCTL がトランスポートプロバイダーでサポートされていない場合にも返されます。このエラーは、UDP または TCP 以外のソケットで SIO_APPLY_TRANSPORT_SETTING IOCTL を使用しようとするとも返されます。

注釈

SIO_APPLY_TRANSPORT_SETTING IOCTL は、Windows 8およびWindows Server 2012以降のバージョンのオペレーティングシステムでサポートされています。

SIO_APPLY_TRANSPORT_SETTING IOCTL は、トランスポート設定をソケットに適用するために使用される汎用 IOCTL です。適用されるトランスポート設定は、lpvInBuffer パラメーターで渡されるTRANSPORT_SETTING_IDに基づいています。

Windows 8とWindows Server 2012以降、システムは TCP ソケットのREAL_TIME_NOTIFICATION_CAPABILITY機能を定義します。 Windows 10とWindows Server 2016以降では、ASSOCIATE_NAMERES_CONTEXTも定義されます。詳細については、「 addrinfoex4 」および 「ASSOCIATE_NAMERES_CONTEXT_INPUT」を参照してください。

lpvInBuffer パラメーターで渡される TRANSPORT_SETTING_ID の Guid メンバーが REAL_TIME_NOTIFICATION_CAPABILITY に設定されている場合、これは、Windows ストアアプリでバックグラウンドネットワーク通知を受信するために ControlChannelTrigger で使用される TCP ソケットのリアルタイム通知設定を適用する要求です。 lpvInBuffer パラメーターは、REAL_TIME_NOTIFICATION_SETTING_INPUT構造体を指す必要があります。この操作では 、lpvOutBuffer パラメーターは使用されません。このトランスポート設定は、TCP ソケットにのみ適用されます。このトランスポート設定は、WinInet または同様のネットワークサービスが、特定の TCP ソケットを ControlChannelTrigger 有効としてマークする方法を提供します。このオプションが呼び出されると、Windows によって対応する TCP ソケットがマークされ、適切なハードウェアとソフトウェアの設定が構成されます。 Windows ストアアプリは、この IOCTL を直接呼び出しません。