GetOverlappedResult 関数 (ioapiset.h)

指定したファイル、名前付きパイプ、または通信デバイスに対して重複した操作の結果を取得します。 タイムアウト間隔を指定するか、アラート可能なスレッドで待機するには、 GetOverlappedResultEx を使用します。

構文

BOOL GetOverlappedResult(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  BOOL         bWait
);

パラメーター

[in] hFile

ファイル、名前付きパイプ、または通信デバイスへのハンドル。 これは、重複した操作が次のいずれかの関数の呼び出しによって開始されたときに指定されたのと同じハンドルです。

• ReadFile
• WriteFile
• ConnectNamedPipe
• TransactNamedPipe
• DeviceIoControl
• WaitCommEvent
• ReadDirectoryChangesW
• LockFileEx

[in] lpOverlapped

重なり合った操作が開始されたときに指定された OVERLAPPED 構造体へのポインター。

[out] lpNumberOfBytesTransferred

読み取りまたは書き込み操作によって実際に転送されたバイト数を受け取る変数へのポインター。 TransactNamedPipe 操作の場合、これはパイプから読み取られたバイト数です。 DeviceIoControl 操作の場合、これはデバイス ドライバーによって返される出力データのバイト数です。 ConnectNamedPipe または WaitCommEvent 操作の場合、この値は未定義です。

[in] bWait

このパラメーターが TRUE で、lpOverlapped 構造体の Internal メンバーがSTATUS_PENDING場合、この関数は操作が完了するまで戻りません。 このパラメーターが FALSE で、操作がまだ保留中の場合、関数は FALSE を 返し、 GetLastError 関数は ERROR_IO_INCOMPLETEを返します。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

GetOverlappedResult 関数によって報告される結果は、指定した OVERLAPPED 構造体が指定され、操作の結果が保留中であった、指定されたハンドルの最後の重複した操作の結果です。 保留中の操作は、操作を開始した関数が FALSE を返し、 GetLastError 関数が ERROR_IO_PENDINGを返したときに示されます。 I/O 操作が保留中の場合、操作を開始した関数は、OVERLAPPED 構造体の hEvent メンバーを非署名状態にリセットします。 その後、保留中の操作が完了すると、システムはイベント オブジェクトをシグナル状態に設定します。

bWait パラメーターが TRUE の場合、GetOverlappedResult は、イベント オブジェクトがシグナル状態になるのを待って保留中の操作が完了したかどうかを判断します。

OVERLAPPED 構造体の hEvent メンバーが NULL の場合、システムは hFile ハンドルの状態を使用して、操作が完了したことを通知します。 この目的でファイル、名前付きパイプ、または通信デバイス ハンドルを使用することはお勧めしません。 同じファイル、名前付きパイプ、または通信デバイスで複数の同時重複操作が実行されると混乱が発生する可能性があるため、イベント オブジェクトを使用する方が安全です。 この状況では、オブジェクトの状態が通知される原因となった操作を知る方法はありません。

例

GetOverlappedResult を使用する例については、「ファイルの終わりのテスト」を参照してください。

要件

関連項目

CancelIo、 CreateEvent、 GetOverlappedResultEx、 OVERLAPPED、 重なり合った入出力、 同期関数