GetOverlappedResultEx 関数 (ioapiset.h)

指定したタイムアウト間隔内で、指定したファイル、名前付きパイプ、または通信デバイスに対して重複した操作の結果を取得します。 呼び出し元のスレッドは、警告可能な待機を実行できます。

構文

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

パラメーター

[in] hFile

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

[in] lpOverlapped

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

[out] lpNumberOfBytesTransferred

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

[in] dwMilliseconds

タイムアウト間隔 (ミリ秒単位)。

dwMilliseconds が 0 で、操作がまだ進行中の場合、関数はすぐにを返し、GetLastError 関数はERROR_IO_INCOMPLETEを返します。

dwMilliseconds が 0 以外で、操作がまだ進行中の場合、関数は、オブジェクトがシグナル通知されるか、I/O 完了ルーチンまたは APC がキューに入るか、または返される前に間隔が経過するまで待機します。 GetLastError を使用して、拡張エラー情報を取得します。

dwMilliseconds が INFINITE の場合、関数は、オブジェクトがシグナル通知された場合、または I/O 完了ルーチンまたは APC がキューに入っている場合にのみを返します。

dwMilliseconds 値には、低電力状態で費やされた時間は含まれません。 たとえば、コンピューターがスリープ状態の間、タイムアウトのカウントダウンは続行されません。

[in] bAlertable

このパラメーターが TRUE で、呼び出し元のスレッドが待機状態の場合、システムが I/O 完了ルーチンまたは APC をキューに入れると、 関数は を返します。 呼び出し元のスレッドは、ルーチンまたは関数を実行します。 それ以外の場合、関数は戻らず、完了ルーチンまたは APC 関数は実行されません。

完了ルーチンは、指定された ReadFileEx または WriteFileEx 関数が完了したときにキューに入れられます。 関数は を返し、完了ルーチンは bAlertable が TRUE の場合にのみ呼び出され、呼び出し元のスレッドは読み取りまたは書き込み操作を開始したスレッドです。 APC がキューに登録されるのは、QueueUserAPC を呼び出したときです。

戻り値

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

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。 一般的なエラー コードは次のとおりです。

• dwMilliseconds が 0 で、操作がまだ進行中の場合、GetLastError はERROR_IO_INCOMPLETEを返します。
• dwMilliseconds が 0 以外で、I/O 完了ルーチンまたは APC がキューに入っている場合、GetLastError はWAIT_IO_COMPLETIONを返します。
• dwMilliseconds が 0 以外で、指定したタイムアウト間隔が経過した場合、GetLastError はWAIT_TIMEOUTを返します。

注釈

GetOverlappedResultEx 関数は、GetOverlappedResult とは次の点で異なります。dwMilliseconds パラメーターは操作のタイムアウト間隔を指定でき、bAlertable パラメーターは呼び出し元のスレッドが警告可能な待機を実行するように指定できます。

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

OVERLAPPED 構造体で手動リセット イベント オブジェクトを指定します。 自動リセット イベント オブジェクトを使用する場合、重複する操作を開始してから GetOverlappedResultEx を呼び出す間隔で、イベント ハンドルを他の待機操作で指定することはできません。 たとえば、イベント オブジェクトは、操作の完了を待機する待機関数のいずれかで指定される場合があります。 待機関数が戻ると、システムは自動リセット イベントの状態を非署名に設定し、dwMilliseconds パラメーターを INFINITE に設定して GetOverlappedResultEx を呼び出すと、関数は無期限にブロックされます。

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

要件

関連項目

CancelIo

ConnectNamedPipe

CreateEvent

DeviceIoControl

GetLastError

GetOverlappedResult

OVERLAPPED

重複した入力と出力

ReadFile

同期関数

TransactNamedPipe

WaitCommEvent

WriteFile