GetQueuedCompletionStatusEx 関数 (ioapiset.h)

[アーティクル]
11/08/2024

複数の完了ポートエントリを同時に取得します。指定した完了ポートに関連付けられている保留中の 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 以降:dwMilliseconds 値には、低電力状態で費やされた時間は含まれません。たとえば、コンピューターがスリープ状態の間、タイムアウトのカウントダウンは続行されません。

[in] fAlertable

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

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

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

戻り値

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

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

備考

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

この関数は、保留中の I/O 少なくとも 1 つが完了したときに TRUE を返しますが、1 つ以上の I/O 操作が失敗した可能性があります。各 OVERLAPPED_ENTRYの lpOverlapped メンバーに含まれる状態を調べることで、lpCompletionPortEntries パラメーターで返されたエントリの一覧を調べて、失敗した可能性のある 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 透過的フェールオーバー (TFO)	はい
SMB 3.0 とスケールアウトファイル共有 (SO)	はい
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性のあるファイルシステム (ReFS)	はい

必要条件

要件	価値
サポートされる最小クライアント	Windows Vista [デスクトップアプリ \|UWP アプリ]
サポートされる最小サーバー	Windows Server 2008 [デスクトップアプリ \|UWP アプリ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	ioapiset.h (Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

GetQueuedCompletionStatusEx 関数 (ioapiset.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース