LPWPUCOMPLETEOVERLAPPEDREQUEST

INT LPWPUCOMPLETEOVERLAPPEDREQUEST(
    SOCKET s,
    OVERLAPPED* lpOverlapped,
    DWORD dwError,
    DWORD cbTransferred,
    INT* lpErrno
);

WPUCompleteOverlappedRequest 関数は、オーバーラップ I/O 操作に対して、オーバーラップ I/O の完了通知を行います。

エラーが発生しなかった場合、 WPUCompleteOverlappedRequest は 0 を返し、クライアントが選択したメカニズムに従ってオーバーラップ I/O 操作の完了を通知します(lpOverlapped が参照する WSAOVERLAPPED 構造体内のイベントをシグナル状態にする、または、ソケットに完了ポートが関連付けられている場合は、その完了ポートに完了ステータスのレポートをキューイングします。あるいはその両方を行います)。それ以外の場合、 WPUCompleteOverlappedRequest は SOCKET_ERROR を返し、具体的なエラーコードは lpErrno で取得できます。

エラーコード	意味
WSAEINVAL	s パラメーターに渡されたソケットが、 WPUCreateSocketHandle によって作成されたソケットではありません。

WPUCompleteOverlappedRequest 関数は、クライアントが指定した完了メカニズムがユーザーモードの非同期プロシージャ呼び出し (APC) 以外である場合に、オーバーラップ I/O 操作の完了通知を行います。この関数は、 WPUCreateSocketHandle によって作成されたソケットハンドルに対してのみ使用できます。

**WPUCompleteOverlappedRequest** 関数は、自身が公開するソケットハンドルに対してインストール可能ファイルシステム (IFS) の機能を直接実装していないサービスプロバイダーが使用します。この関数は、指定された完了通知がユーザーモード APC 以外であるすべてのオーバーラップ I/O 要求について、完了通知を行います。 **WPUCompleteOverlappedRequest** がサポートされるのは WPUCreateSocketHandle によって作成されたソケットハンドルだけであり、サービスプロバイダーが直接作成したソケットではサポートされません。

クライアントが通知方法としてユーザーモード APC を選択した場合、サービスプロバイダーは WPUQueueApc または他の適切なオペレーティングシステム関数を使用して完了通知を行う必要があります。クライアントがユーザーモード APC を選択しなかった場合、IFS の機能を直接実装していないサービスプロバイダーは、クライアントがソケットハンドルに完了ポートを関連付けたかどうかを判断できません。そのため、完了通知の方法が、完了ポートへの完了ステータスレコードのキューイングであるべきか、 WSAOVERLAPPED 構造体内のイベントのシグナル通知であるべきかを判断できません。Windows Socket 2 のアーキテクチャは、 WPUCreateSocketHandle によって作成されたソケットに対する完了ポートの関連付けを追跡しており、完了ポートベースの通知とイベントベースの通知のどちらを使用するかを正しく判断できます。

WPUCompleteOverlappedRequest は、完了の通知をキューイングする際に、 WSAOVERLAPPED 構造体の InternalHigh メンバーに転送されたバイト数を設定します。次に、Internal メンバーに、特別な値である WSS_OPERATION_IN_PROGRESS 以外の OS 依存の値を設定します。処理が非同期に行われる場合があるため、 WPUCompleteOverlappedRequest が制御を返してからこれらの値が反映されるまでに、わずかな遅延が生じることがあります。ただし、Internal が設定される時点までに InternalHigh の値(バイト数)が設定されていることは保証されます。

WPUCompleteOverlappedRequest は、ソケットハンドルに完了ポートが関連付けられているかどうかにかかわらず、前述のとおりに動作します(クライアントが要求したとおりに完了通知を行います)。

WSPGetOverlappedResult との相互作用

WPUCompleteOverlappedRequest の動作は、サービスプロバイダーが WSPGetOverlappedResult をどのように実装するかに、いくつかの制約を課します。というのも、 WSAOVERLAPPED 構造体のうちサービスプロバイダーが排他的に制御できるのは Offset メンバーと OffsetHigh メンバーだけであるにもかかわらず、 WSPGetOverlappedResult は 3 つの値(バイト数、フラグ、エラー)をこの構造体から取得しなければならないためです。サービスプロバイダーは、 WPUCompleteOverlappedRequest の動作と適切に連携する限り、任意の方法でこれを実現できます。ただし、一般的な実装は次のとおりです。

• オーバーラップ処理の開始時に、サービスプロバイダーは Internal に WSS_OPERATION_IN_PROGRESS を設定します。
• I/O 操作が完了したら、プロバイダーは OffsetHigh に操作の結果として生じた Windows Socket 2 のエラーコードを設定し、Offset に I/O 操作の結果として生じたフラグを設定して、転送バイト数をパラメーターの 1 つとして渡して WPUCompleteOverlappedRequest を呼び出します。 WPUCompleteOverlappedRequest は最終的に InternalHigh に転送バイト数を設定し、続いて Internal に WSS_OPERATION_IN_PROGRESS 以外の値を設定します。
• WSPGetOverlappedResult が呼び出されると、サービスプロバイダーは Internal を確認します。その値が WSS_OPERATION_IN_PROGRESS である場合、プロバイダーは WSPGetOverlappedResult の FWAIT フラグの設定に応じて、hEvent メンバーのイベントハンドルを待機するか、エラーを返します。処理中でない場合、または待機が完了した後は、プロバイダーは InternalHigh、OffsetHigh、Offset の値を、それぞれ転送バイト数、操作結果のエラーコード、フラグとして返します。