GetQueuedCompletionStatusEx 関数
複数の完了ポート エントリを同時に取得します。 指定された完了ポートに関連付けられている保留中の 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
);
パラメーター
-
CompletionPort [in]
-
完了ポートへのハンドル。 完了ポートを作成するには、 CreateIoCompletionPort 関数を使用します。
-
lpCompletionPortEntries [out]
-
入力時に、 OVERLAPPED_ENTRY 構造体の事前に割り当てられた配列を指します。
出力時に、 はエントリを保持 するOVERLAPPED_ENTRY 構造体の配列を受け取ります。 配列要素の数は、 ulNumEntriesRemoved によって提供されます。
各 I/O 中に転送されたバイト数、各 I/O が発生したファイルを示す入力候補キー、および各元の I/O で使用される重複する構造体アドレスはすべて lpCompletionPortEntries 配列で返されます。
-
ulCount [in]
-
削除するエントリの最大数。
-
ulNumEntriesRemoved [out]
-
実際に削除されたエントリの数を受け取る変数へのポインター。
-
dwMilliseconds [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 の値には、低電力で費やされた時間は含まれません状態。 たとえば、コンピューターがスリープ状態の間にタイムアウトがカウントダウンし続けないようにします。
-
fAlertable [in]
-
このパラメーターが FALSE の場合、タイムアウト期間が経過するか、エントリが取得されるまで関数は戻りません。
パラメーターが TRUE で 、使用可能なエントリがない場合、関数はアラート可能な待機を実行します。 システムが I/O 完了ルーチンまたは APC をスレッドにキューに入れ、スレッドが関数を実行すると、スレッドは を返します。
完了ルーチンは、指定された ReadFileEx 関数または WriteFileEx 関数が完了し、呼び出し元のスレッドが操作を開始したスレッドである場合にキューに入れられます。 QueueUserAPC を呼び出すと、APC がキューに入れられます。
戻り値
成功した場合は 0 以外の値 (TRUE) を返し、それ以外の場合は 0 (FALSE) を返します。
詳細なエラー情報を得るには、GetLastError を呼び出します。
注釈
この関数は、指定した完了ポートにスレッドを関連付けます。 スレッドは、最大 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 操作が完了すると、先入れ先出し順にこのポートにキューに入れられます。 スレッドがこの呼び出しをアクティブに待機している場合は、キューに置かれた 1 つ以上の要求がそのスレッドの呼び出しのみを完了します。
I/O 完了ポートの理論、使用法、および関連する関数の詳細については、「 I/O 完了ポート」を参照してください。
Windows 8とWindows Server 2012では、この関数は次のテクノロジでサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル |
はい |
| SMB 3.0 Transparent Failover (TFO) |
はい |
| SMB 3.0 とスケールアウト ファイル共有 (SO) |
Yes |
| クラスター共有ボリューム ファイル システム (CsvFS) |
Yes |
| Resilient File System (ReFS) |
Yes |
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント |
Windows Vista [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー |
Windows Server 2008 [デスクトップ アプリ |UWP アプリ] |
| ヘッダー |
|
| ライブラリ |
|
| [DLL] |
|