GetQueuedCompletionStatusEx 関数

2025-05-08

複数の完了ポートエントリを同時に取得します。指定した完了ポートに関連付けられている保留中の I/O 操作が完了するまで待機します。

I/O 完了パケットを一度に 1 つずつデキューするには、 GetQueuedCompletionStatus 関数を使用します。

構文

BOOL WINAPI GetQueuedCompletionStatusEx(
  _In_  HANDLE             CompletionPort,
  _Out_ LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  _In_  ULONG              ulCount,
  _Out_ PULONG             ulNumEntriesRemoved,
  _In_  DWORD              dwMilliseconds,
  _In_  BOOL               fAlertable
);

パラメーター

コンプリートポート[in]

完了ポートへのハンドル。完了ポートを作成するには、 CreateIoCompletionPort 関数を使用します。

lpCompletionPortEntries[out]

入力時に、事前に割り当てられた OVERLAPPED_ENTRY 構造体の配列を指します。

出力時に、エントリを保持する OVERLAPPED_ENTRY 構造体の配列を受け取ります。配列要素の数は、 ulNumEntriesRemoved によって提供されます。

各 I/O 中に転送されたバイト数、各 I/O が発生したファイルを示す完了キー、および元の各 I/O で使用された重複する構造体アドレスはすべて lpCompletionPortEntries 配列に返されます。

ulCount (ウルカウント)[in]

削除するエントリの最大数。

ulNumEntries削除済み[out]

実際に削除されたエントリの数を受け取る変数へのポインター。

dwミリ秒[in]

呼び出し元が完了ポートに完了パケットが表示されるのを待機するミリ秒数。指定した時間内に完了パケットが表示されない場合、関数はタイムアウトして FALSEを返します。

dwMilliseconds が INFINITE (0xFFFFFFFF) の場合、関数はタイムアウトしません。dwMilliseconds が 0 で、デキューする I/O 操作がない場合、関数はすぐにタイムアウトします。

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 値には、低電力状態で費やされた時間は含まれません。たとえば、コンピューターがスリープ状態の間、タイムアウトはカウントダウンを続けません。

fアラート可能[in]

このパラメーターが FALSEの場合、タイムアウト期間が経過するか、エントリが取得されるまで、関数は戻りません。

パラメータが TRUE で、使用可能なエントリがない場合、関数はアラート可能な待機を実行します。スレッドは、システムが I/O 完了ルーチンまたは APC をスレッドにキューイングし、スレッドが関数を実行すると戻ります。

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

戻り値

成功した場合は 0 以外の TRUE を返し、それ以外の場合は 0 FALSE を返します。

詳細なエラー情報を取得するには、GetLastError を呼び出します。

注釈

この関数は、指定された完了ポートにスレッドを関連付けます。 1 つのスレッドは、最大 1 つの完了ポートに関連付けることができます。

この関数は、少なくとも 1 つの保留中の I/O が完了したときに TRUE を返しますが、1 つ以上の I/O 操作が失敗した可能性があります。この関数のユーザーは、lpCompletionPortEntries パラメーターで返されたエントリの一覧を確認し、各OVERLAPPED_ENTRYの lpOverlapped メンバーに含まれる状態を確認して、失敗した可能性のある I/O 操作に対応するエントリを特定する必要があります。

この関数は、I/O 操作がデキューされなかった場合に FALSE を返します。これは通常、この呼び出しのパラメーターの処理中にエラーが発生したか、 CompletionPort ハンドルが閉じられたか無効であることを意味します。 GetLastError 関数は、拡張エラー情報を提供します。

GetQueuedCompletionStatusEx の呼び出しが、関連付けられているハンドルが閉じられたために失敗した場合、関数は FALSE を返し、GetLastError は ERROR_ABANDONED_WAIT_0 を返します。

サーバーアプリケーションには、同じ完了ポートに対して GetQueuedCompletionStatusEx 関数を呼び出す複数のスレッドがある場合があります。 I/O 操作が完了すると、I/O 操作は先入れ先出しの順序でこのポートにキューに入れられます。スレッドがこの呼び出しをアクティブに待機している場合、キューに入れられた 1 つ以上の要求がそのスレッドの呼び出しのみを完了します。

I/O 完了ポートの理論、使用方法、および関連する機能の詳細については、「 I/O 完了ポート」を参照してください。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジでサポートされています。

テクノロジー	サポートされています
サーバーメッセージブロック (SMB) 3.0 プロトコル	イエス
SMB 3.0 透過的フェールオーバー (TFO)	イエス
SMB 3.0 とスケールアウトファイル共有 (SO)	イエス
クラスター共有ボリュームファイルシステム (CsvFS)	イエス
回復性のあるファイルシステム (ReFS)	イエス

要求事項

要件	価値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリ \|UWP アプリ]
ヘッダ	`IoAPI.h` ( `Windows.h`を含む) `WinBase.h` Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista ( `Windows.h`を含む)
図書館	`Kernel32.lib`
[DLL]	`Kernel32.dll`