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