LPFN_RIOSENDEX
コールバックシグネチャ
BOOL LPFN_RIOSENDEX(
RIO_RQ SocketQueue,
RIO_BUF* pData,
DWORD DataBufferCount,
RIO_BUF* pLocalAddress,
RIO_BUF* pRemoteAddress,
RIO_BUF* pControlContext,
RIO_BUF* pFlags,
DWORD Flags,
void* RequestContext
);パラメーター
| フィールド | 型 | 説明 |
|---|---|---|
| SocketQueue | RIO_RQ | 接続済みの登録 I/O TCP ソケット、またはバインドされた登録 I/O UDP ソケットを識別する記述子。 |
| pData | RIO_BUF* | データの送信元となる、登録されたバッファー内のバッファーセグメント。このパラメーターが指す RIO_BUF 構造体は、登録されたバッファーの一部または登録されたバッファー全体を表すことができます。 アプリケーションが UDP データグラムでデータペイロードを送信する必要がない場合、バインドされた登録 I/O UDP ソケットではこのパラメーターを NULL にできます。 |
| DataBufferCount | DWORD | pData パラメーターが指すバッファー内のデータを送信するかどうかを示す、データバッファー数のパラメーター。 pData が NULL の場合、このパラメーターは 0 に設定します。それ以外の場合は 1 に設定します。 |
| pLocalAddress | RIO_BUF* | このパラメーターは予約されており、NULL でなければなりません。 |
| pRemoteAddress | RIO_BUF* | 登録されたバッファー内のバッファーセグメントで、入力時にネットワークデータの送信先となるリモートアドレスを保持します。 ソケットが接続済みの場合、このパラメーターは NULL でもかまいません。 |
| pControlContext | RIO_BUF* | 完了時に、送信操作に関する追加の制御情報を保持するバッファースライス。 アプリケーションが追加の制御情報を受け取る必要がない場合、このパラメーターは NULL でもかまいません。 |
| pFlags | RIO_BUF* | 完了時に、送信操作のフラグセットに関する追加情報を保持するバッファースライス。 アプリケーションが追加のフラグ情報を受け取る必要がない場合、このパラメーターは NULL でもかまいません。 |
| Flags | DWORD | RIOSendEx 関数の動作を変更するフラグのセット。 Flags パラメーターには、 RIO_MSG_COMMIT_ONLYRIO_MSG_DEFER フラグを指定して追加された以前の要求がコミットされます。 RIO_MSG_COMMIT_ONLY フラグを設定する場合、他のフラグは指定できません。RIO_MSG_COMMIT_ONLY フラグを設定する場合、pData、pLocalAddress、pRemoteAddress、pControlContext、pFlags、RequestContext の各引数は NULL でなければならず、DataBufferCount 引数は 0 でなければなりません。 このフラグは通常、RIO_MSG_DEFER フラグを設定した要求を複数発行した後に、ときどき使用します。これにより、RIO_MSG_DEFER フラグを使用する際に最後の要求だけを RIO_MSG_DEFER フラグなしで発行する必要がなくなります。最後の要求をフラグなしで発行すると、その要求は他の要求よりも完了が大幅に遅くなります。 RIOSendEx 関数の他の呼び出しとは異なり、RIO_MSG_COMMIT_ONLY フラグを設定した場合は、RIOSendEx 関数の呼び出しをシリアル化する必要はありません。単一の RIO_RQ に対して、あるスレッドで RIO_MSG_COMMIT_ONLY を指定して RIOSendEx 関数を呼び出しながら、別のスレッドで RIOSendEx 関数を呼び出すことができます。 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* | この送信操作に関連付ける要求コンテキスト。 |
公式ドキュメント
RIOSendEx 関数は、接続済みの登録 I/O TCP ソケット、またはバインドされた登録 I/O UDP ソケットでネットワークデータを送信します。Winsock 登録 I/O 拡張機能で使用する追加オプションを指定できます。
戻り値
エラーが発生しない場合、RIOSendEx 関数は TRUE を返します。この場合、送信操作は正常に開始されており、完了が既にキューに登録されているか、操作が正常に開始されて完了が後でキューに登録されます。
FALSE は、関数が失敗し、操作が正常に開始されず、完了通知もキューに登録されないことを示します。具体的なエラーコードは、WSAGetLastError 関数を呼び出して取得できます。
| リターンコード | 説明 |
|---|---|
| WSAEFAULT | 呼び出しでポインター引数を使用しようとした際に、システムが無効なポインターアドレスを検出しました。このエラーは、操作がキューに登録または呼び出される前に、パラメーターとして渡された RIO_BUF 構造体のいずれかについて、バッファー識別子の登録が解除されたか、バッファーが解放された場合に返されます。 |
| WSAEINVAL | 無効なパラメーターが関数に渡されました。 このエラーは、SocketQueue パラメーターが有効でない場合、Flags パラメーターに送信操作では無効な値が含まれる場合、または完了キューの整合性が損なわれた場合に返されます。パラメーターに関するその他の問題でも、このエラーが返されることがあります。 |
| WSAENOBUFS | 十分なメモリを割り当てられませんでした。このエラーは、SocketQueue パラメーターに関連付けられた I/O 完了キューが満杯である場合、または I/O 完了キューが送信エントリ数 0 で作成された場合に返されます。 |
| WSA_IO_PENDING | 操作は正常に開始され、完了は後でキューに登録されます。 |
解説(Remarks)
アプリケーションは RIOSendEx 関数を使用して、単一の登録されたバッファー内に完全に収まる任意のバッファーからネットワークデータを送信できます。pData パラメーターが指す RIO_BUF 構造体の Offset メンバーと Length メンバーによって、バッファーから送信されるネットワークデータが決まります。
送信操作に関連付けられたバッファーは、別の送信操作または受信操作と同時に使用してはなりません。バッファーおよびそのバッファー登録は、送信操作が続いている間、有効なままでなければなりません。つまり、RIOSend(Ex) 要求が既に保留中の場合に、同じ PRIO_BUF を RIOSend(Ex) 要求へ渡してはいけません。実行中の RIOSend(Ex) 要求が完了した後で初めて、同じ PRIO_BUF を(同じオフセットで、あるいは別のオフセットと長さで)再利用できます。さらに、送信データが登録されたバッファー(その一部またはバッファー全体)を参照している場合、送信が完了するまで、その登録されたバッファー全体を使用してはなりません。これには、登録されたバッファーの一部を受信操作や別の送信操作に使用することも含まれます。
pLocalAddress パラメーターは、データの送信元となったローカルアドレスの取得に使用できます。pRemoteAddress パラメーターは、データの送信先となったリモートアドレスの取得に使用できます。ローカルアドレスとリモートアドレスは、SOCKADDR_INET 構造体として返されます。そのため、pLocalAddress または pRemoteAddress パラメーターが指す RIO_BUF の Length メンバーは、SOCKADDR_INET 構造体のサイズ以上である必要があります。
次の表は、pControlContext メンバーの制御情報で使用できる制御データのさまざまな用途をまとめたものです。
| プロトコル | cmsg_level | cmsg_type | 説明 |
|---|---|---|---|
| IPv4 | IPPROTO_IP | IP_PKTINFO | パケット情報を指定/受信します。 詳細については、IP_PKTINFO ソケットオプションに関する IPPROTO_IP ソケットオプション を参照してください。 |
| IPv6 | IPPROTO_IPV6 | IPV6_DSTOPTS | 宛先オプションを指定/受信します。 |
| IPv6 | IPPROTO_IPV6 | IPV6_HOPLIMIT | ホップ制限を指定/受信します。 詳細については、IPV6_HOPLIMIT ソケットオプションに関する IPPROTO_IPV6 ソケットオプション を参照してください。 |
| IPv6 | IPPROTO_IPV6 | IPV6_HOPOPTS | ホップバイホップオプションを指定/受信します。 |
| IPv6 | IPPROTO_IPV6 | IPV6_NEXTHOP | ネクストホップアドレスを指定します。 |
| IPv6 | IPPROTO_IPV6 | IPV6_PKTINFO | パケット情報を指定/受信します。 詳細については、IPV6_PKTINFO ソケットオプションに関する IPPROTO_IPV6 ソケットオプション を参照してください。 |
| IPv6 | IPPROTO_IPV6 | IPV6_RTHDR | ルーティングヘッダーを指定/受信します。 |
制御データは 1 つ以上の制御データオブジェクトで構成され、それぞれが次のように定義された WSACMSGHDR 構造体で始まります。
} WSACMSGHDR;
WSACMSGHDR 構造体のメンバーは次のとおりです。
| 用語 | 説明 |
|---|---|
| cmsg_len | WSACMSGHDR の先頭からデータの末尾までのデータのバイト数(データの後に続く可能性があるパディングバイトは含みません)。 |
| cmsg_level | 制御情報の発信元となったプロトコル。 |
| cmsg_type | プロトコル固有の制御情報の種類。 |
Flags パラメーターを使用すると、関連付けられたソケットに指定されたオプションの範囲を超えて、RIOSendEx 関数の動作に影響を与えることができます。この関数の動作は、SocketQueue パラメーターに関連付けられたソケットに設定されたソケットオプションと、Flags パラメーターで指定された値の組み合わせによって決まります。
RIOSendEx 関数への関数ポインターは、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)