LPWSPGETOVERLAPPEDRESULT

LPWSPGetOverlappedResult 関数は、指定されたソケットに対するオーバーラップ操作の結果を返します。

LPWSPGetOverlappedResult が成功した場合、戻り値は TRUE です。これは、オーバーラップ操作が正常に完了し、lpcbTransfer が指す値が更新されたことを意味します。LPWSPGetOverlappedResult が FALSE を返した場合は、オーバーラップ操作が完了していない、オーバーラップ操作がエラーを伴って完了した、または LPWSPGetOverlappedResult に渡された 1 つ以上のパラメーターのエラーにより完了状態を判別できなかったことを意味します。失敗した場合、lpcbTransfer が指す値は更新されません。lpErrno パラメーターは、失敗の原因(LPWSPGetOverlappedResult 自体の失敗、または関連するオーバーラップ操作の失敗のいずれか)を示します。

LPWSPGetOverlappedResult 関数が報告する結果は、指定された WSAOverlapped 構造体が渡され、かつ操作の結果が保留中であった、指定ソケットの最後のオーバーラップ操作の結果です。操作を開始した関数が SOCKET_ERROR を返し、lpErrno が WSA_IO_PENDING である場合、その操作が保留中であることを示します。I/O 操作が保留中の場合、操作を開始した関数は WSAOVERLAPPED 構造体の hEvent メンバーを非シグナル状態にリセットします。その後、保留中の操作が完了すると、システムはイベントオブジェクトをシグナル状態に設定します。

fWait パラメーターが TRUE の場合、LPWSPGetOverlappedResult は、イベントオブジェクトがシグナル状態になるのをブロックして待機することにより、保留中の操作が完了したかどうかを判断します。クライアントが fWait パラメーターに TRUE を設定できるのは、I/O 操作を要求したときにイベントベースの完了通知を選択した場合のみです。別の形式の通知を選択した場合、WSAOverlapped 構造体の hEvent メンバーの用途は異なるため、fWait に TRUE を設定すると予測できない結果になります。

WPUCompleteOverlappedRequest との相互作用

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

オーバーラップ処理の開始時に、サービスプロバイダーは Internal を WSS_OPERATION_IN_PROGRESS に設定します。

I/O 操作が完了すると、プロバイダーは OffsetHigh に操作の結果として得られた Windows Sockets 2 のエラーコードを設定し、Offset に I/O 操作の結果として得られたフラグを設定したうえで、転送バイト数をパラメーターの 1 つとして渡して WPUCompleteOverlappedRequest を呼び出します。WPUCompleteOverlappedRequest は最終的に InternalHigh に転送バイト数を設定し、続いて Internal を WSS_OPERATION_IN_PROGRESS 以外の値に設定します。

LPWSPGetOverlappedResult が呼び出されると、サービスプロバイダーは Internal を確認します。それが WSS_OPERATION_IN_PROGRESS の場合、プロバイダーは LPWSPGetOverlappedResult の fWait フラグの設定に応じて、hEvent メンバーのイベントハンドルを待機するか、エラーを返します。進行中でない場合、または待機の完了後は、プロバイダーは InternalHigh、OffsetHigh、Offset の値を、それぞれ転送バイト数、操作結果のエラーコード、フラグとして返します。