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 では、この関数は、次のテクノロジによってサポートされています。

必要条件

関連項目

ConnectNamedPipe

CreateIoCompletionPort

DeviceIoControl

File Management 関数

関数

GetQueuedCompletionStatusEx

I/O 完了ポート

LockFileEx

概要トピック

PostQueuedCompletionStatus

ReadFile

TransactNamedPipe

Windows ヘッダーの使用

WaitCommEvent

WriteFile