LPFN_RIORECEIVE
コールバックシグネチャ
BOOL LPFN_RIORECEIVE(
RIO_RQ SocketQueue,
RIO_BUF* pData,
DWORD DataBufferCount,
DWORD Flags,
void* RequestContext
);パラメーター
| フィールド | 型 | 説明 |
|---|---|---|
| SocketQueue | RIO_RQ | 接続済みの登録済み I/O TCP ソケット、またはバインド済みの登録済み I/O UDP ソケットを識別する記述子。 |
| pData | RIO_BUF* | データを受信する登録済みバッファーの該当部分の記述。 アプリケーションが UDP データグラムのデータペイロードを受信する必要がない場合、バインド済みの登録済み I/O UDP ソケットではこのパラメーターに NULL を指定できます。 |
| DataBufferCount | DWORD | pData パラメーターが指すバッファーでデータを受信するかどうかを示すデータバッファー数のパラメーター。 pData が NULL の場合、このパラメーターには 0 を設定します。それ以外の場合は 1 を設定します。 |
| Flags | DWORD | RIOReceive 関数の動作を変更するフラグのセット。 Flags パラメーターには、 RIO_MSG_COMMIT_ONLYRIO_MSG_DEFER フラグを指定して追加された以前の要求がコミットされます。 RIO_MSG_COMMIT_ONLY フラグを設定する場合、他のフラグは指定できません。RIO_MSG_COMMIT_ONLY フラグを設定する場合、pData および RequestContext 引数は NULL でなければならず、DataBufferCount 引数は 0 でなければなりません。 このフラグは通常、RIO_MSG_DEFER フラグを設定した要求をいくつか発行した後に、随時使用します。これにより、RIO_MSG_DEFER フラグを使用する際に最後の要求だけを RIO_MSG_DEFER フラグなしで発行する必要がなくなります。そのようにすると、最後の要求の完了が他の要求よりも大幅に遅くなります。 RIOReceive 関数の他の呼び出しとは異なり、RIO_MSG_COMMIT_ONLY フラグを設定した場合は、RIOReceive 関数の呼び出しをシリアル化する必要はありません。単一の RIO_RQ に対して、あるスレッドで RIO_MSG_COMMIT_ONLY を指定して RIOReceive 関数を呼び出しながら、別のスレッドで RIOReceive 関数を呼び出すことができます。 RIO_MSG_DONT_NOTIFY要求の完了がその完了キューに挿入されるときに、要求が RIONotify 関数をトリガーしないようにします。 RIO_MSG_DEFER要求を直ちに実行する必要がないことを示します。要求は要求キューに挿入されますが、要求の実行がトリガーされる場合とされない場合があります。 データの受信は、SocketQueue パラメーターで渡された RIO_RQ に対して RIO_MSG_DEFER フラグを設定しない受信要求が行われるまで、遅延される可能性があります。要求キュー内のすべての受信の実行をトリガーするには、RIO_MSG_DEFER フラグを設定せずに RIOReceive 関数または RIOReceiveEx 関数を呼び出します。 メモ
受信要求は、RIO_MSG_DEFER が設定されているかどうかにかかわらず、SocketQueue パラメーターで渡された RIO_RQ の未処理 I/O 容量に計上されます。 RIO_MSG_WAITALLRIOReceive 関数は、次のいずれかのイベントが発生するまで完了しません。
このフラグは UDP ソケットではサポートされません。 |
| RequestContext | void* | この受信操作に関連付ける要求コンテキスト。 |
公式ドキュメント
RIOReceive 関数は、Winsock 登録済み I/O 拡張機能で使用するために、接続済みの登録済み I/O TCP ソケット、またはバインド済みの登録済み I/O UDP ソケットでネットワークデータを受信します。
戻り値
エラーが発生しない場合、RIOReceive 関数は TRUE を返します。この場合、受信操作は正常に開始されており、完了が既にキューに入れられているか、または操作が正常に開始され完了が後でキューに入れられます。
FALSE は、関数が失敗し、操作が正常に開始されず、完了通知がキューに入れられないことを示します。具体的なエラーコードは、WSAGetLastError 関数を呼び出して取得できます。
| 戻り値 | 説明 |
|---|---|
| WSAEFAULT | 呼び出しでポインター引数を使用しようとした際に、システムが無効なポインターアドレスを検出しました。このエラーは、操作がキューに入れられるか呼び出されるよりも前に、パラメーターで渡された RIO_BUF 構造体のいずれかについて、バッファー識別子が登録解除された場合、またはバッファーが解放された場合に返されます。 |
| WSAEINVAL | 無効なパラメーターが関数に渡されました。 このエラーは、SocketQueue パラメーターが有効でない場合、Flags パラメーターに受信操作では無効な値が含まれている場合、または完了キューの整合性が損なわれている場合に返されます。このエラーは、パラメーターに関するその他の問題でも返されることがあります。 |
| WSAENOBUFS | 十分なメモリを割り当てられませんでした。このエラーは、SocketQueue パラメーターに関連付けられた I/O 完了キューがいっぱいである場合、または I/O 完了キューが受信エントリ数 0 で作成された場合に返されます。 |
| WSA_OPERATION_ABORTED | 受信操作が保留中に操作が取り消されました。このエラーは、ソケットがローカルまたはリモートで閉じられた場合、あるいはこのソケットに対して WSAIoctl の SIO_FLUSH コマンドが実行された場合に返されます。 |
解説(Remarks)
アプリケーションは、RIOReceive 関数を使用して、単一の登録済みバッファー内に完全に収まる任意のバッファーへネットワークデータを受信できます。ネットワークデータをバッファー内のどこに受信するかは、pData パラメーターが指す RIO_BUF 構造体の Offset メンバーと Length メンバーによって決まります。
RIOReceive 関数を呼び出した後は、pData パラメーターで渡されたバッファー（RIO_BUF 構造体の BufferId メンバーに含まれる RIO_BUFFERID を含む）は、受信操作が完了するまで有効なままでなければなりません。
競合状態を避けるため、受信要求に関連付けられたバッファーは、その要求が完了するまで読み取りや書き込みを行わないでください。これには、そのバッファーを送信要求の送信元として使用することや、別の受信要求の宛先として使用することも含まれます。どの受信要求にも関連付けられていない登録済みバッファーの部分は、この制限の対象外です。
Flags パラメーターを使用すると、関連付けられたソケットに指定されたオプションを超えて、RIOReceive 関数の呼び出しの動作に影響を与えることができます。この関数の動作は、SocketQueue パラメーターに関連付けられたソケットに設定されたソケットオプションと、Flags パラメーターで指定された値の組み合わせによって決まります。
RIOReceive 関数への関数ポインターは、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 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)