ホーム › System.IO › GetQueuedCompletionStatus

GetQueuedCompletionStatus

関数

I/O完了ポートから完了したI/O結果を取り出す。

DLLKERNEL32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// KERNEL32.dll
#include <windows.h>

BOOL GetQueuedCompletionStatus(
    HANDLE CompletionPort,
    DWORD* lpNumberOfBytesTransferred,
    UINT_PTR* lpCompletionKey,
    OVERLAPPED** lpOverlapped,
    DWORD dwMilliseconds
);

パラメーター

名前	型	方向	説明
CompletionPort	HANDLE	in	完了ポートへのハンドルです。完了ポートを作成するには、 CreateIoCompletionPort 関数を使用してください。
lpNumberOfBytesTransferred	DWORD*	out	完了した I/O 操作で転送されたバイト数を受け取る変数へのポインターです。
lpCompletionKey	UINT_PTR*	out	I/O 操作が完了したファイルハンドルに関連付けられた完了キー値を受け取る変数へのポインターです。完了キーは、 CreateIoCompletionPort の呼び出しで指定される、ファイルごとのキーです。
lpOverlapped	OVERLAPPED**	out	完了した I/O 操作が開始されたときに指定された OVERLAPPED 構造体のアドレスを受け取る変数へのポインターです。完了ポートに関連付けられたファイルハンドルと有効な OVERLAPPED 構造体を関数に渡した場合でも、アプリケーションは完了ポート通知を抑制できます。これは、OVERLAPPED 構造体の hEvent メンバーに有効なイベントハンドルを指定し、その最下位ビットを設定することで行います。最下位ビットが設定された有効なイベントハンドルは、オーバーラップ I/O の完了時に完了パケットが完了ポートにエンキューされるのを抑制します。
dwMilliseconds	DWORD	in	完了パケットが完了ポートに現れるのを呼び出し側が待機する時間(ミリ秒単位)です。指定された時間内に完了パケットが現れなかった場合、関数はタイムアウトして FALSE を返し、*lpOverlapped を NULL に設定します。 dwMilliseconds が INFINITE の場合、関数はタイムアウトしません。dwMilliseconds がゼロで、デキューする 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 値には、低電力状態で費やされた時間は含まれません。たとえば、コンピューターがスリープ状態の間はタイムアウトのカウントダウンは継続しません。

戻り値の型: BOOL

公式ドキュメント

指定された I/O 完了ポートから I/O 完了パケットのデキューを試みます。

戻り値

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

拡張エラー情報を取得するには、 GetLastError を呼び出してください。

詳細については、「解説」セクションを参照してください。

解説(Remarks)

この関数は、指定された完了ポートにスレッドを関連付けます。1 つのスレッドは、最大で 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 Completion Ports」を参照してください。

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

テクノロジ	サポート
Server Message Block (SMB) 3.0 プロトコル	はい
SMB 3.0 トランスペアレントフェールオーバー (TFO)	はい
SMB 3.0 とスケールアウトファイル共有 (SO)	はい
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性ファイルシステム (ReFS)	はい

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll
#include <windows.h>

BOOL GetQueuedCompletionStatus(
    HANDLE CompletionPort,
    DWORD* lpNumberOfBytesTransferred,
    UINT_PTR* lpCompletionKey,
    OVERLAPPED** lpOverlapped,
    DWORD dwMilliseconds
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool GetQueuedCompletionStatus(
    IntPtr CompletionPort,   // HANDLE
    out uint lpNumberOfBytesTransferred,   // DWORD* out
    out UIntPtr lpCompletionKey,   // UINT_PTR* out
    IntPtr lpOverlapped,   // OVERLAPPED** out
    uint dwMilliseconds   // DWORD
);

<DllImport("KERNEL32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function GetQueuedCompletionStatus(
    CompletionPort As IntPtr,   ' HANDLE
    <Out> ByRef lpNumberOfBytesTransferred As UInteger,   ' DWORD* out
    <Out> ByRef lpCompletionKey As UIntPtr,   ' UINT_PTR* out
    lpOverlapped As IntPtr,   ' OVERLAPPED** out
    dwMilliseconds As UInteger   ' DWORD
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' CompletionPort : HANDLE
' lpNumberOfBytesTransferred : DWORD* out
' lpCompletionKey : UINT_PTR* out
' lpOverlapped : OVERLAPPED** out
' dwMilliseconds : DWORD
Declare PtrSafe Function GetQueuedCompletionStatus Lib "kernel32" ( _
    ByVal CompletionPort As LongPtr, _
    ByRef lpNumberOfBytesTransferred As Long, _
    ByRef lpCompletionKey As LongPtr, _
    ByVal lpOverlapped As LongPtr, _
    ByVal dwMilliseconds As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetQueuedCompletionStatus = ctypes.windll.kernel32.GetQueuedCompletionStatus
GetQueuedCompletionStatus.restype = wintypes.BOOL
GetQueuedCompletionStatus.argtypes = [
    wintypes.HANDLE,  # CompletionPort : HANDLE
    ctypes.POINTER(wintypes.DWORD),  # lpNumberOfBytesTransferred : DWORD* out
    ctypes.POINTER(ctypes.c_size_t),  # lpCompletionKey : UINT_PTR* out
    ctypes.c_void_p,  # lpOverlapped : OVERLAPPED** out
    wintypes.DWORD,  # dwMilliseconds : DWORD
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
GetQueuedCompletionStatus = Fiddle::Function.new(
  lib['GetQueuedCompletionStatus'],
  [
    Fiddle::TYPE_VOIDP,  # CompletionPort : HANDLE
    Fiddle::TYPE_VOIDP,  # lpNumberOfBytesTransferred : DWORD* out
    Fiddle::TYPE_VOIDP,  # lpCompletionKey : UINT_PTR* out
    Fiddle::TYPE_VOIDP,  # lpOverlapped : OVERLAPPED** out
    -Fiddle::TYPE_INT,  # dwMilliseconds : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn GetQueuedCompletionStatus(
        CompletionPort: *mut core::ffi::c_void,  // HANDLE
        lpNumberOfBytesTransferred: *mut u32,  // DWORD* out
        lpCompletionKey: *mut usize,  // UINT_PTR* out
        lpOverlapped: *mut *mut OVERLAPPED,  // OVERLAPPED** out
        dwMilliseconds: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true)]
public static extern bool GetQueuedCompletionStatus(IntPtr CompletionPort, out uint lpNumberOfBytesTransferred, out UIntPtr lpCompletionKey, IntPtr lpOverlapped, uint dwMilliseconds);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetQueuedCompletionStatus' -Namespace Win32 -PassThru
# $api::GetQueuedCompletionStatus(CompletionPort, lpNumberOfBytesTransferred, lpCompletionKey, lpOverlapped, dwMilliseconds)

#uselib "KERNEL32.dll"
#func global GetQueuedCompletionStatus "GetQueuedCompletionStatus" sptr, sptr, sptr, sptr, sptr
; GetQueuedCompletionStatus CompletionPort, varptr(lpNumberOfBytesTransferred), varptr(lpCompletionKey), varptr(lpOverlapped), dwMilliseconds   ; 戻り値は stat
; CompletionPort : HANDLE -> "sptr"
; lpNumberOfBytesTransferred : DWORD* out -> "sptr"
; lpCompletionKey : UINT_PTR* out -> "sptr"
; lpOverlapped : OVERLAPPED** out -> "sptr"
; dwMilliseconds : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global GetQueuedCompletionStatus "GetQueuedCompletionStatus" sptr, var, var, var, int
; res = GetQueuedCompletionStatus(CompletionPort, lpNumberOfBytesTransferred, lpCompletionKey, lpOverlapped, dwMilliseconds)
; CompletionPort : HANDLE -> "sptr"
; lpNumberOfBytesTransferred : DWORD* out -> "var"
; lpCompletionKey : UINT_PTR* out -> "var"
; lpOverlapped : OVERLAPPED** out -> "var"
; dwMilliseconds : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global GetQueuedCompletionStatus "GetQueuedCompletionStatus" sptr, sptr, sptr, sptr, int
; res = GetQueuedCompletionStatus(CompletionPort, varptr(lpNumberOfBytesTransferred), varptr(lpCompletionKey), varptr(lpOverlapped), dwMilliseconds)
; CompletionPort : HANDLE -> "sptr"
; lpNumberOfBytesTransferred : DWORD* out -> "sptr"
; lpCompletionKey : UINT_PTR* out -> "sptr"
; lpOverlapped : OVERLAPPED** out -> "sptr"
; dwMilliseconds : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。