LPFN_RIORECEIVEEX コールバック関数 (mswsock.h)

[アーティクル]
09/23/2023

RIOReceiveEx 関数は、接続された登録済み I/O TCP ソケットまたはバインドされた登録済み I/O UDP ソケット上のネットワークデータを受信し、Winsock 登録済み I/O 拡張機能で使用するための追加オプションを使用します。

構文

LPFN_RIORECEIVEEX LpfnRioreceiveex;

int LpfnRioreceiveex(
                                                                                                                     RIO_RQ SocketQueue,
                                                                                                                     PRIO_BUF pData,
                                                                                                                     ULONG DataBufferCount,
                                                                                                                     PRIO_BUF pLocalAddress,
                                                                                                                     PRIO_BUF pRemoteAddress,
                                                                                                                     PRIO_BUF pControlContext,
                                                                                                                     PRIO_BUF pFlags,
                                                                                                                     DWORD Flags,
                                                                                                                     PVOID RequestContext
)
{...}

パラメーター

SocketQueue

接続された登録済み I/O UDP ソケットまたはバインドされた登録済み I/O UDP ソケットを識別する記述子。

pData

データを受信する登録済みバッファーの部分の説明。

アプリケーションが UDP データグラムでデータペイロードを受信する必要がない場合、バインドされた登録済み I/O UDP ソケットの場合、このパラメーターは NULL になる可能性があります。

DataBufferCount

pData パラメーターが指すバッファーでデータを受信するかどうかを示すデータバッファーカウントパラメーター。

pData が NULL の場合、このパラメーターは 0 に設定する必要があります。それ以外の場合は、このパラメーターを 1 に設定する必要があります。

pLocalAddress

完了時に、ネットワークデータが受信されたローカルアドレスを保持するバッファーセグメント。

アプリケーションがローカルアドレスを受信しない場合、このパラメーターは NULL になる可能性があります。このパラメーターが NULL でない場合、バッファーセグメントは 少なくとも SOCKADDR_INET 構造体のサイズである必要があります。

pRemoteAddress

完了時に、ネットワークデータの受信元のリモートアドレスを保持するバッファーセグメント。

アプリケーションがリモートアドレスを受信しない場合、このパラメーターは NULL になる可能性があります。このパラメーターが NULL でない場合、バッファーセグメントは 少なくとも SOCKADDR_INET 構造体のサイズである必要があります。

pControlContext

完了時に受信操作に関する追加の制御情報を保持するバッファースライス。

アプリケーションが追加の制御情報を受け取らない場合、このパラメーターは NULL になる可能性があります。

pFlags

Flags

RIOReceiveEx 関数の動作を変更するフラグのセット。

Flags パラメーターには、ヘッダーファイルでMswsockdef.h定義されている次のオプションの組み合わせを含めることができます。

RIO_MSG_COMMIT_ONLY

RIO_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 フラグなしで最後の要求を行う必要がなくなります。これにより、最後の要求が他の要求よりもはるかに遅く完了します。

RIOReceiveEx 関数の他の呼び出しとは異なり、RIO_MSG_COMMIT_ONLY フラグが設定されている場合、RIOReceiveEx 関数の呼び出しをシリアル化する必要はありません。 1 つのRIO_RQの場合、RIOReceiveEx 関数は、別のスレッドで RIOReceiveEx 関数を呼び出している間に、あるスレッドで RIO_MSG_COMMIT_ONLYを使用して呼び出すことができます。

RIO_MSG_DONT_NOTIFY

要求の完了が完了キューに挿入された場合、要求は RIONotify 関数をトリガーしないでください。

RIO_MSG_DEFER

要求をすぐに実行する必要はありません。これにより要求が要求キューに挿入されますが、要求の実行がトリガーされる場合とトリガーされない場合があります。

RIO_MSG_DEFER フラグを設定せずに SocketQueue パラメーターで渡RIO_RQに対して受信要求が行われるまで、データ受信が遅延する可能性があります。要求キュー内のすべての受信に対して実行をトリガーするには、RIO_MSG_DEFER フラグを設定せずに RIOReceive または RIOReceiveEx 関数を呼び出します。

注意

受信要求は、RIO_MSG_DEFERが設定されているかどうかに関係なく、SocketQueue パラメーターで渡されたRIO_RQの未処理の I/O 容量に対して課金されます。

RIO_MSG_WAITALL

RIOReceiveEx 関数は、次のいずれかのイベントが発生するまで完了しません。

pData パラメーターで呼び出し元によって提供されるバッファースライスがいっぱいです。
接続は閉じられました。
要求が取り消されたか、エラーが発生しました。

このフラグは、データグラムソケットまたはメッセージ指向のコネクションレスソケットではサポートされていません。

RequestContext

この受信操作に関連付ける要求コンテキスト。

戻り値

エラーが発生しない場合、 RIOReceiveEx 関数は TRUE を返します。この場合、受信操作は正常に開始され、完了は既にキューに登録されているか、操作が正常に開始され、完了は後でキューに入れられます。

FALSE の値は、関数が失敗し、操作が正常に開始されず、完了通知がキューに登録されないことを示します。 WSAGetLastError 関数を呼び出すことで、特定のエラーコードを取得できます。

リターンコード	説明
WSAEFAULT	呼び出しでポインター引数を使用しようとしたときに、システムにより、無効なポインターアドレスが検出されました。このエラーは、操作がキューに登録または呼び出される前にパラメーターで渡された RIO_BUF 構造体のいずれかに対してバッファー ID が登録解除されたか、バッファーが解放された場合に返されます。
WSAEINVAL	無効なパラメーターが関数に渡されました。 SocketQueue パラメーターが無効な場合、dwFlags パラメーターに受信操作に無効な値が含まれている場合、または完了キューの整合性が損なわれた場合、このエラーが返されます。このエラーは、パラメーターに関する他の問題でも返すことができます。
WSAENOBUFS	十分なメモリを割り当てませんでした。 SocketQueue パラメーターに関連付けられている I/O 完了キューがいっぱいであるか、受信エントリが 0 個の I/O 完了キューが作成された場合、このエラーが返されます。
WSA_OPERATION_ABORTED	受信操作が保留中の間に操作が取り消されました。このエラーは、ソケットがローカルまたはリモートで閉じているか、 WSAIoctl の SIO_FLUSH コマンドが実行された場合に返されます。

注釈

アプリケーションでは 、RIOReceiveEx 関数を使用して、登録されている 1 つのバッファー内に完全に格納されている任意のバッファーにネットワークデータを受信できます。 pData パラメーターが指すRIO_BUF構造体の Offset メンバーと Length メンバーは、バッファー内のネットワークデータを受信する場所を決定します。

RIOReceiveEx 関数が呼び出されると、RIO_BUF 構造体のBufferId メンバーのRIO_BUFFERIDを含む pData パラメーターに渡されるバッファーは、受信操作の間有効なままである必要があります。

競合状態を回避するために、要求が完了する前に、受信要求に関連付けられているバッファーを読み取ったり書き込んだりしないでください。これには、送信要求のソースとしてバッファーを使用するか、別の受信要求の送信先を使用することも含まれます。受信要求に関連付けられていない登録済みバッファーの一部は、この制限には含まれません。

pLocalAddress パラメーターを使用して、データが受信されたローカルアドレスを取得できます。 pRemoteAddress パラメーターを使用して、データの受信元のリモートアドレスを取得できます。ローカルアドレスとリモートアドレスは、 SOCKADDR_INET 構造体として返されます。その結果、pLocalAddress パラメーターまたは pRemoteAddress パラメーターが指すRIO_BUFの Length メンバーは、SOCKADDR_INET構造体のサイズ以上である必要があります。

次の表は、 pControlContext メンバーのコントロール情報で使用できるコントロールデータのさまざまな使用方法をまとめたものです。

Protocol	cmsg_level	cmsg_type	説明
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	データグラムソケットのパケットが受信された元の IPv4 到着インターフェイスを受信します。この制御データは、IPv4 NAT トラバーサルにTeredo、6to4、または ISATAP トンネルが使用される場合にファイアウォールによって使用されます。 cmsg_data[] メンバーは、 ifdef.h ヘッダーファイルで定義されているIF_INDEXを含む ULONG です。詳細については、「 IP_ORIGINAL_ARRIVAL_IF ソケットオプションのIPPROTO_IP ソケットオプション」を参照してください。
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 パラメーターを使用すると、関連するソケットに指定されたオプションを超えて 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 ストアアプリでサポートされています。

要件

要件	値
Header	mswsock.h

次の方法で共有