LPFN_RIOSEND
コールバックシグネチャ
BOOL LPFN_RIOSEND(
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 | RIOSend 関数の動作を変更するフラグのセットです。 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 フラグなしで発行する必要がなくなります。そのような最後の要求は、他の要求よりも完了がはるかに遅くなります。 RIOSend 関数の他の呼び出しとは異なり、RIO_MSG_COMMIT_ONLY フラグを設定した場合、RIOSend 関数の呼び出しを直列化する必要はありません。単一の RIO_RQ に対して、あるスレッドで RIO_MSG_COMMIT_ONLY を指定して RIOSend 関数を呼び出しながら、別のスレッドで RIOSend 関数を呼び出すことができます。 RIO_MSG_DONT_NOTIFY要求の完了が完了キューに挿入されるときに、その要求が RIONotify 関数をトリガーしないようにします。 RIO_MSG_DEFER要求を直ちに実行する必要はありません。要求は要求キューに挿入されますが、要求の実行がトリガーされる場合とされない場合があります。 SocketQueue パラメーターで渡された RIO_RQ に対して、RIO_MSG_DEFER フラグを設定しない送信要求が行われるまで、データの送信が遅延することがあります。送信キュー内のすべての送信の実行をトリガーするには、RIO_MSG_DEFER フラグを設定せずに RIOSend 関数または RIOSendEx 関数を呼び出します。 メモ
送信要求は、RIO_MSG_DEFER が設定されているかどうかにかかわらず、SocketQueue パラメーターで渡された RIO_RQ の未処理 I/O 容量に対して計上されます。 |
| RequestContext | void* |
公式ドキュメント
RIOSend 関数は、Winsock の登録された I/O 拡張機能で使用するために、接続済みの登録された I/O TCP ソケット、またはバインド済みの登録された I/O UDP ソケットでネットワークデータを送信します。
戻り値
エラーが発生しない場合、RIOSend 関数は TRUE を返します。この場合、送信操作は正常に開始されており、完了が既にキューに登録されているか、または操作が正常に開始されて完了が後でキューに登録されます。
FALSE の値は、関数が失敗し、操作が正常に開始されず、完了通知もキューに登録されないことを示します。具体的なエラーコードは、WSAGetLastError 関数を呼び出して取得できます。
| 戻り値 | 説明 |
|---|---|
| WSAEFAULT | 呼び出しでポインター引数を使用しようとした際に、システムが無効なポインターアドレスを検出しました。このエラーは、操作がキューに登録される前、または呼び出される前に、パラメーターで渡された RIO_BUF 構造体のいずれかについて、バッファー識別子が登録解除されたか、バッファーが解放された場合に返されます。 |
| WSAEINVAL | 無効なパラメーターが関数に渡されました。 このエラーは、SocketQueue パラメーターが有効でない場合、Flags パラメーターに送信操作では無効な値が含まれる場合、または完了キューの整合性が損なわれている場合に返されます。このエラーは、パラメーターに関するその他の問題でも返されることがあります。 |
| WSAENOBUFS | 十分なメモリを割り当てられませんでした。このエラーは、SocketQueue パラメーターに関連付けられた I/O 完了キューが満杯である場合、または I/O 完了キューが送信エントリ数 0 で作成された場合に返されます。 |
| WSA_IO_PENDING | 操作は正常に開始され、完了は後でキューに登録されます。 |
解説(Remarks)
アプリケーションは、RIOSend 関数を使用して、単一の登録されたバッファー内に完全に含まれる任意のバッファーからネットワークデータを送信できます。送信されるネットワークデータは、pData パラメーターが指す RIO_BUF 構造体の Offset メンバーと Length メンバーによって決まります。
送信操作に関連付けられたバッファーを、別の送信操作や受信操作と同時に使用してはなりません。バッファーおよびそのバッファー登録は、送信操作の実行中は有効なままである必要があります。つまり、ある RIOSend(Ex) 要求が保留中のときに、同じ PRIO_BUF を RIOSend(Ex) 要求に渡してはなりません。実行中の RIOSend(Ex) 要求が完了した後にのみ、同じ PRIO_BUF を(同じオフセットで、または異なるオフセットと長さで)再利用できます。さらに、送信データが登録されたバッファー(その一部または全体)を参照する場合、送信が完了するまで、その登録されたバッファー全体を使用してはなりません。これには、登録されたバッファーの一部を受信操作や別の送信操作に使用することも含まれます。
Flags パラメーターを使用すると、関連付けられたソケットに指定されたオプションの範囲を超えて、RIOSend 関数の動作に影響を与えることができます。この関数の動作は、SocketQueue パラメーターに関連付けられたソケットに設定されたソケットオプションと、Flags パラメーターで指定された値の組み合わせによって決まります。
RIOSend 関数への関数ポインターは、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)