GetQueuedCompletionStatus 함수(ioapiset.h)

아티클
05/20/2023

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를 호출합니다.

자세한 내용은 주의 섹션을 참조하세요.

설명

이 함수는 스레드를 지정된 완료 포트와 연결합니다. 하나의 스레드는 최대 하나의 완료 포트와 연결할 수 있습니다.

호출이 미해결 상태인 동안 연결된 완료 포트 핸들이 닫혀 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 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	Yes

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	ioapiset.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll