GetQueuedCompletionStatusEx 関数 (ioapiset.h)
複数の完了ポート エントリを同時に取得します。 指定した完了ポートに関連付けられている保留中の I/O 操作が完了するまで待機します。
I/O 完了パケットを 1 つずつデキューする場合は、GetQueuedCompletionStatus 関数を使います。
構文
BOOL GetQueuedCompletionStatusEx(
[in] HANDLE CompletionPort,
[out] LPOVERLAPPED_ENTRY lpCompletionPortEntries,
[in] ULONG ulCount,
[out] PULONG ulNumEntriesRemoved,
[in] DWORD dwMilliseconds,
[in] BOOL fAlertable
);
パラメーター
[in] CompletionPort
完了ポートへのハンドル。 完了ポートを作成するには、CreateIoCompletionPort 関数を使います。
[out] lpCompletionPortEntries
入力時に、OVERLAPPED_ENTRY 構造体の事前割り当て済み配列を指します。
出力時に、エントリを保持する OVERLAPPED_ENTRY 構造体の配列を受け取ります。 配列の要素数は ulNumEntriesRemoved で指定されます。
各 I/O 中に転送されたバイト数、各 I/O がどのファイルで発生したかを示す完了キー、元の各 I/O で使われた重複する構造体アドレスは、すべて lpCompletionPortEntries 配列で返されます。
[in] ulCount
削除するエントリの最大数。
[out] ulNumEntriesRemoved
実際に削除されたエントリ数を受け取る変数のポインター。
[in] dwMilliseconds
完了ポートに完了パケットが届くまで呼び出し元が待機するミリ秒数。 指定した時間内に完了パケットが届かなかった場合、関数はタイムアウトして 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 値には低電力状態で経過した時間は含まれません。 たとえば、コンピューターがスリープ状態の間、タイムアウトのカウントダウンは続行されません。
[in] fAlertable
このパラメーターが FALSE の場合、タイムアウト期間が経過するか、エントリが取得されるまで、この関数は戻りません。
このパラメーターが TRUE であり、使用できるエントリがない場合、この関数は警告可能な待機を実行します。 I/O 完了ルーチンまたは APC がシステムによってスレッドのキューに登録され、スレッドによってその関数が実行されると、スレッドは戻ります。
完了ルーチンがキューに登録されるのは、指定した ReadFileEx または WriteFileEx 関数が完了したとき、かつ呼び出し元スレッドが操作を開始したスレッドである場合です。 APC がキューに登録されるのは、QueueUserAPC を呼び出したときです。
戻り値
成功した場合は 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) | はい |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | はい |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | ioapiset.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |
関連項目
関数
概要トピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示