GetOverlappedResultEx 関数 (ioapiset.h)

[アーティクル]
08/24/2023

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

構文

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 がキューに入っている場合にのみを返します。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008、Windows Server 2008 R2: dwMilliseconds 値には、低電力状態で費やされた時間が含まれます。たとえば、コンピューターがスリープ状態の間、タイムアウトはカウントダウンを続けます。

Windows 8、Windows Server 2012、Windows 8.1、Windows Server 2012 R2、Windows 10、Windows Server 2016: 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 ハンドルの状態を使用して、操作が完了したことを通知します。この目的でファイル、名前付きパイプ、または通信デバイスハンドルを使用することはお勧めしません。同じファイル、名前付きパイプ、または通信デバイスで複数の同時重複操作が実行されると混乱が発生する可能性があるため、イベントオブジェクトを使用する方が安全です。この状況では、オブジェクトの状態が通知される原因となった操作を知る方法はありません。

要件

要件	値
サポートされている最小のクライアント	Windows 8 [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2012 [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	ioapiset.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

Share via

GetOverlappedResultEx 関数 (ioapiset.h)

構文

パラメーター

戻り値

注釈

要件

関連項目

フィードバック

フィードバック

その他のリソース