WPUCompleteOverlappedRequest

WPUCompleteOverlappedRequest 関数は、オーバーラップ I/O 操作の完了通知を行う。

WPUCompleteOverlappedRequest s, lpOverlapped, dwError, cbTransferred, lpErrno

s : [int] WPUCreateSocketHandle で生成されたサービスプロバイダソケット。
lpOverlapped : [var] 完了通知対象のオーバーラップ I/O 操作に関連付けられた WSAOVERLAPPED 構造体へのポインタ。
dwError : [int] 完了通知対象のオーバーラップ I/O 操作の完了ステータス。
cbTransferred : [int] クライアントバッファとの間で転送されたバイト数 (転送方向は、完了通知対象のオーバーラップ I/O 操作が送信・受信のどちらの性質であるかに依存する)。
lpErrno : [var] この関数の実行結果として得られるエラーコードへのポインタ。

(プラグイン / モジュール : ws2_32.dll)

解説

WPUCompleteOverlappedRequest 関数は、オーバーラップ I/O 操作の完了通知を行う。

[戻り値]
エラーがない場合、**WPUCompleteOverlappedRequest** はゼロを返し、クライアントが選択した機構
(lpOverlapped が参照する WSAOVERLAPPED
構造体内のイベントのシグナリングや、ソケットに完了ポートが関連付けられている場合は完了ポートへの完了ステータスレポートのキューイング)
に従ってオーバーラップ I/O 操作の完了を通知する。そうでない場合、**WPUCompleteOverlappedRequest** は
SOCKET_ERROR を返し、具体的なエラーコードは lpErrno で取得できる。
（以下省略）

[備考]
**WPUCompleteOverlappedRequest**
関数は、クライアントが指定した完了通知機構がユーザーモード非同期プロシージャコール (APC) 以外である場合のオーバーラップ I/O
操作の完了通知を行う。この関数は WPUCreateSocketHandle
で生成されたソケットハンドルに対してのみ使用できる。**注** この関数は、"WPU"
プレフィックスを持つ他の関数とは異なり、アップコールテーブル経由ではアクセスされない。代わりに Ws2_32.dll
から直接エクスポートされる。この関数を呼び出す必要があるサービスプロバイダは WS2_32.lib とリンクするか、LoadLibrary
や GetProcAddress 等の適切な OS
関数を使って関数ポインタを取得すべきである。**WPUCompleteOverlappedRequest**
関数は、公開するソケットハンドルに対して IFS (Installable File System)
機能を直接実装していないサービスプロバイダが使用する。この関数は、完了通知がユーザーモード APC 以外であるオーバーラップ I/O
リクエストに対して完了通知を行う。**WPUCompleteOverlappedRequest** は
WPUCreateSocketHandle
で生成されたソケットハンドルに対してのみサポートされ、サービスプロバイダが直接生成したソケットにはサポートされない。クライアントが通知方法としてユーザーモード
APC を選んだ場合、サービスプロバイダは WPUQueueApc または他の適切な OS
関数を使って完了通知を行うべきである。ユーザーモード APC がクライアントから選択されていない場合、IFS
機能を直接実装していないサービスプロバイダは、クライアントが完了ポートをソケットハンドルに関連付けているかを知ることができない。したがって、完了通知方法が完了ポートへのステータスレコードキューイングであるべきか、WSAOVERLAPPED
構造体内のイベントのシグナリングであるべきかを判断できない。Windows Socket 2
アーキテクチャは、WPUCreateSocketHandle
で生成されたソケットと完了ポートとの関連付けを追跡しており、完了ポート方式かイベント方式かを正しく判断できる。**WPUCompleteOverlappedRequest**
は完了通知をキューイングする際、WSAOVERLAPPED 構造体の **InternalHigh**
メンバに転送バイト数を設定し、その後 **Internal** メンバを特殊値 WSS_OPERATION_IN_PROGRESS 以外の
OS 依存値に設定する。処理は非同期に行われる可能性があるため、**WPUCompleteOverlappedRequest**
の戻りから実際にこれらの値が見えるまでにはわずかな遅延が生じうる。ただし、**InternalHigh** 値 (バイト数) は
**Internal**
が設定される時点までに必ず設定されることが保証される。**WPUCompleteOverlappedRequest**
は、ソケットハンドルが完了ポートと関連付けられているかどうかに関わらず、記載の通り (クライアントが要求した完了通知を行う)
動作する。**WSPGetOverlappedResult との相互作用**
**WPUCompleteOverlappedRequest** の動作は、サービスプロバイダによる
WSPGetOverlappedResult の実装方法にいくつかの制約を与える。これは、WSAOVERLAPPED
構造体のうちサービスプロバイダが排他的に制御できるのは **Offset** と **OffsetHigh** の 2
メンバのみであるのに対し、**WSPGetOverlappedResult** はバイト数、フラグ、エラーの 3
つの値を構造体から取得しなければならないためである。サービスプロバイダは、**WPUCompleteOverlappedRequest**
の動作と正しく連携する限り、この要件を任意の方法で満たせる。ただし、典型的な実装は次の通りである。
- オーバーラップ処理の開始時、サービスプロバイダは **Internal** を WSS_OPERATION_IN_PROGRESS
に設定する。- I/O 操作が完了したら、プロバイダは **OffsetHigh** に Windows Socket 2
エラーコードを、**Offset** に I/O 操作で得られたフラグを設定し、転送バイト数をパラメータとして
**WPUCompleteOverlappedRequest**
を呼び出す。**WPUCompleteOverlappedRequest** は最終的に **InternalHigh**
に転送バイト数を設定し、その後 **Internal** を WSS_OPERATION_IN_PROGRESS 以外の値に設定する。-
WSPGetOverlappedResult が呼び出されたら、サービスプロバイダは **Internal** を確認する。それが
WSS_OPERATION_IN_PROGRESS ならば、プロバイダは **WSPGetOverlappedResult** の
FWAIT フラグの設定に応じて **hEvent**
メンバのイベントハンドルで待機するか、エラーを返す。進行中でない場合、または待機完了後には、プロバイダは
**InternalHigh**、**OffsetHigh**、**Offset**
の値をそれぞれ転送数、操作結果エラーコード、フラグとして返す。

情報