GetQueuedCompletionStatus 関数 (ioapiset.h)

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

指定した 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 以降: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呼び出します。

I/O 完了ポートの理論、使用法、および関連する関数の詳細については、「I/O 完了ポートを参照してください。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジでサポートされています。

テクノロジー	サポート
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 透過的フェールオーバー (TFO)	はい
SMB 3.0 とスケールアウトファイル共有 (SO)	はい
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性のあるファイルシステム (ReFS)	はい

必要条件

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

次の方法で共有

GetQueuedCompletionStatus 関数 (ioapiset.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース