GetQueuedCompletionStatus 関数 (ioapiset.h)
指定した I/O 入力候補ポートから I/O 完了パケットのデキューを試みます。 キューに登録された完了パケットがない場合、関数は完了ポートに関連付けられている保留中の I/O 操作が完了するまで待機します。
複数の I/O 完了パケットを一度にデキューするには、 GetQueuedCompletionStatusEx 関数を 使用します。
構文
BOOL GetQueuedCompletionStatus(
[in] HANDLE CompletionPort,
LPDWORD lpNumberOfBytesTransferred,
[out] PULONG_PTR lpCompletionKey,
[out] LPOVERLAPPED *lpOverlapped,
[in] DWORD dwMilliseconds
);
パラメーター
[in] CompletionPort
入力候補ポートへのハンドル。 完了ポートを作成するには、 CreateIoCompletionPort 関数を使用します。
lpNumberOfBytesTransferred
完了した I/O 操作で転送されたバイト数を受け取る変数へのポインター。
[out] lpCompletionKey
I/O 操作が完了したファイル ハンドルに関連付けられている完了キー値を受け取る変数へのポインター。 完了キーは、 CreateIoCompletionPort の呼び出しで指定されるファイルごとのキーです。
[out] lpOverlapped
完了した I/O 操作の開始時に指定 された OVERLAPPED 構造体のアドレスを受け取る変数へのポインター。
完了ポートと有効な OVERLAPPED 構造体に関連付けられたファイル ハンドルを関数に渡した場合でも、アプリケーションは完了ポート通知を防ぐことができます。 これを行うには、OVERLAPPED 構造体の hEvent メンバーに有効なイベント ハンドルを指定し、その下位ビットを設定します。 下位ビットが設定されている有効なイベント ハンドルを使用すると、重複した I/O が完了パケットを完了ポートにエンキューできなくなります。
[in] dwMilliseconds
完了パケットが完了ポートに表示されるまで呼び出し元が待機するミリ秒数。 指定した時間内に完了パケットが表示されない場合、関数はタイムアウトし、 FALSE を返し、*lpOverlapped を NULL に設定 します。
dwMilliseconds が INFINITE の場合、関数はタイムアウトしません。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 の値には、低電力で費やされた時間は含まれません状態。 たとえば、コンピューターがスリープ状態の間、タイムアウトがカウントダウンし続けられません。
戻り値
成功した場合は 0 以外 (TRUE)、それ以外の場合は 0 (FALSE) を返します。
詳細なエラー情報を得るには、GetLastError を呼び出します。
詳細については、「解説」を参照してください。
解説
この関数は、指定した完了ポートにスレッドを関連付けます。 スレッドは、最大 1 つの完了ポートに関連付けることができます。
GetQueuedCompletionStatus の呼び出しが失敗し、呼び出しが未処理の間に関連付けられている完了ポート ハンドルが閉じられている場合、関数は FALSE を返し、*lpOverlapped は NULL になり、GetLastError はERROR_ABANDONED_WAIT_0を返します。
Windows Server 2003 および Windows XP: 呼び出しが未処理の間に完了ポート ハンドルを閉じると、前に示した動作は発生しません。 この関数は、エントリがポートから削除されるまで、または INFINITE 以外の値として指定されている場合にタイムアウトが発生するまで待機し続けます。
GetQueuedCompletionStatus 関数が成功した場合、完了ポートから正常な I/O 操作の完了パケットをデキューし、lpNumberOfBytes、lpCompletionKey、lpOverlapped の各パラメーターが指す変数に情報を格納します。 失敗した場合 (戻り値は FALSE)、これらの同じパラメーターに次のように特定の値の組み合わせを含めることができます。
- *lpOverlapped が NULL の場合、関数は完了ポートから完了パケットをデキューしませんでした。 この場合、この関数は lpNumberOfBytes パラメーターと lpCompletionKey パラメーターによって指される変数に情報を格納せず、それらの値は不確定です。
- *lpOverlapped が NULL ではなく、関数が完了ポートから失敗した I/O 操作の完了パケットをデキューする場合、この関数は、失敗した操作に関する情報を lpNumberOfBytes、 lpCompletionKey、 lpOverlapped が指す変数に格納します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
Windows 8とWindows Server 2012では、この関数は次のテクノロジでサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 Transparent Failover (TFO) | はい |
| スケールアウト ファイル共有を含む SMB 3.0 (SO) | はい |
| クラスター共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | ioapiset.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |
関連項目
関数
概要に関するトピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示