ホーム › Networking.WinSock › LPFN_RIOCREATEREQUESTQUEUE

LPFN_RIOCREATEREQUESTQUEUE

コールバック

シグネチャ

RIO_RQ LPFN_RIOCREATEREQUESTQUEUE(
    SOCKET Socket,
    DWORD MaxOutstandingReceive,
    DWORD MaxReceiveDataBuffers,
    DWORD MaxOutstandingSend,
    DWORD MaxSendDataBuffers,
    RIO_CQ ReceiveCQ,
    RIO_CQ SendCQ,
    void* SocketContext
);

パラメーター

フィールド	型	説明
Socket	SOCKET	ソケットを識別する記述子。
MaxOutstandingReceive	DWORD	ソケット上で許可される未完了の受信の最大数。このパラメーターは、ほとんどのアプリケーションでは通常小さな値になります。
MaxReceiveDataBuffers	DWORD	ソケット上の受信データバッファーの最大数。メモ Windows 8 および Windows Server 2012 では、このパラメーターは 1 でなければなりません。
MaxOutstandingSend	DWORD	ソケット上で許可される未完了の送信の最大数。
MaxSendDataBuffers	DWORD	ソケット上の送信データバッファーの最大数。メモ Windows 8 および Windows Server 2012 では、このパラメーターは 1 でなければなりません。
ReceiveCQ	RIO_CQ	受信要求の完了に使用する I/O 完了キューを識別する記述子。
SendCQ	RIO_CQ	送信要求の完了に使用する I/O 完了キューを識別する記述子。このパラメーターには ReceiveCQ パラメーターと同じ値を指定できます。
SocketContext	void*	この要求キューに関連付けるソケットコンテキスト。

公式ドキュメント

RIOCreateRequestQueue 関数は、Winsock の登録 I/O 拡張機能で使用するために、指定されたソケットと I/O 完了キューを使用して登録 I/O ソケット記述子を作成します。

戻り値

エラーが発生しなかった場合、RIOCreateRequestQueue 関数は新しい要求キューを参照する記述子を返します。それ以外の場合は RIO_INVALID_RQ が返され、WSAGetLastError 関数を呼び出すことで固有のエラーコードを取得できます。

リターンコード	説明
WSAEINVAL	無効なパラメーターが関数に渡されました。このエラーは、ReceiveCQ または SendCQ パラメーターに RIO_INVALID_CQ が含まれていた場合に返されます。また、MaxOutstandingReceive パラメーターと MaxOutstandingSend パラメーターの両方が 0 の場合にも返されます。さらに、Socket パラメーターで渡されたソケットが初期化中または終了処理中の場合にも返されます。
WSAENOBUFS	十分なメモリーを割り当てられませんでした。このエラーは、指定されたパラメーターに基づいて要求キューを割り当てるのに十分なメモリーがなかった場合に返されます。また、ネットワークセッションの上限を超えた場合にも返されます。
WSAENOTSOCK	記述子がソケットではありません。このエラーは、Socket パラメーターが有効なソケットでない場合に返されます。
WSAEOPNOTSUPP	参照されているオブジェクトの種類では、試行された操作はサポートされていません。このエラーは、Socket パラメーターにサポートされていない種類のソケット (SOCK_RAW など) が指定された場合に返されます。

解説(Remarks)

RIOCreateRequestQueue 関数は、指定されたソケットと I/O 完了キューを使用して登録 I/O ソケット記述子を作成します。アプリケーションは、RIOSend、RIOSendEx、RIOReceive、RIOReceiveEx の各関数を使用する前に、RIOCreateRequestQueue を呼び出して Winsock ソケット用の RIO_RQ を取得する必要があります。RIO_RQ を取得するには、Winsock ソケットが送信用と受信用の完了キューに関連付けられている必要がありますが、両方に同じ完了キューを使用することもできます。

完了キューのサイズは有限であるため、ソケットは、キューに入る完了の総数が容量を超えないことを保証できる場合に限り、送信および受信操作用の完了キューに関連付けることができます。そのため、RIOCreateRequestQueue 関数の呼び出しによってソケット固有の上限が設定されます。これらの上限は、RIOCreateRequestQueue の呼び出し時にソケットの要求を収容できる十分な空きが完了キューにあることを確認するためと、要求の開始時にその要求によってソケットが上限を超えないことを確認するための両方で使用されます。

送信キューと受信キューは、複数のソケットに関連付けることができます。送信キューと受信キューのサイズは、関連付けられているすべてのソケットの送信サイズおよび受信サイズ以上でなければなりません。closesocket 関数でソケットを閉じて要求キューが閉じられると、それらのスロットは解放され、他のソケットが使用できるようになります。

メモ

効率上の理由から、完了キュー (RIO_CQ 構造体) および要求キュー (RIO_RQ 構造体) へのアクセスは同期プリミティブで保護されていません。複数のスレッドから完了キューまたは要求キューにアクセスする必要がある場合は、クリティカルセクション、スリムリーダー/ライターロック、または同様のメカニズムでアクセスを調整する必要があります。単一のスレッドからのアクセスであれば、このロックは不要です。異なるスレッドがそれぞれ別の要求キュー/完了キューにアクセスする場合は、ロックなしで行えます。同期が必要になるのは、複数のスレッドが同じキューにアクセスしようとする場合のみです。また、送信および受信操作ではソケットの要求キューが使用されるため、複数のスレッドが同じソケットで送信や受信を発行する場合も同期が必要です。

アプリケーションは、RIO_RQ の使用を終えたら、closesocket 関数を呼び出してソケットを閉じ、関連するリソースを解放する必要があります。

メモ

RIOCreateRequestQueue 関数への関数ポインターは、SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER オペコードを指定して WSAIoctl 関数を呼び出すことにより、実行時に取得する必要があります。WSAIoctl 関数に渡す入力バッファーには、Winsock の登録 I/O 拡張関数を識別する値を持つグローバル一意識別子 (GUID) である WSAID_MULTIPLE_RIO を格納する必要があります。成功すると、WSAIoctl 関数が返す出力には、Winsock の登録 I/O 拡張関数へのポインターを格納した RIO_EXTENSION_FUNCTION_TABLE 構造体へのポインターが含まれます。SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL は Ws2def.h ヘッダーファイルで定義されています。WSAID_MULTIPLE_RIO GUID は Mswsock.h ヘッダーファイルで定義されています。

Windows Phone 8: この関数は、Windows Phone 8 以降の Windows Phone ストアアプリでサポートされています。

Windows 8.1 および Windows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされています。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)