GetQueuedCompletionStatusEx 함수(ioapiset.h)

아티클
08/24/2023

여러 완료 포트 항목을 동시에 검색합니다. 지정된 완료 포트와 연결된 보류 중인 I/O 작업이 완료될 때까지 기다립니다.

I/O 완료 패킷을 한 번에 하나씩 큐에서 제거하려면 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, Windows 8.1, Windows Server 2012 R2, Windows 10 및 Windows Server 2016: 절전 상태에서 소요된 시간이 dwMilliseconds 값에 포함되지 않습니다. 예를 들어 컴퓨터가 절전 모드인 동안 시간 제한은 계속 카운트다운되지 않습니다.

[in] fAlertable

이 매개 변수가 FALSE이면 제한 시간이 경과하거나 항목을 가져올 때까지 함수가 반환되지 않습니다.

매개 변수가 TRUE이고 사용 가능한 항목이 없는 경우 함수는 경고 가능한 대기를 수행합니다. 스레드는 시스템이 I/O 완료 루틴 또는 APC를 스레드의 큐에 추가하고 스레드가 함수를 실행할 때 반환됩니다.

완료 루틴은 지정된 ReadFileEx 또는 WriteFileEx 함수가 완료되고 호출 스레드가 작업을 시작하는 스레드일 때 큐에 추가됩니다. QueueUserAPC를 호출하면 APC가 큐에 추가됩니다.

반환 값

성공하면 0이 아닌 값(TRUE)을 반환하고, 그렇지 않으면 0(FALSE)을 반환합니다.

확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

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

이 함수는 보류 중인 I/O가 하나 이상 완료될 때 TRUE를 반환하지만, 하나 이상의 I/O 작업이 실패했을 수도 있습니다. 각 OVERLAPPED_ENTRY의 lpOverlapped 멤버에 포함된 상태를 확인하여 lpCompletionPortEntries 매개 변수에서 반환된 항목 목록을 확인하여 실패 가능성이 있는 I/O 작업에 해당하는 항목을 확인하는 것은 이 함수의 사용자에게 달려 있습니다.

이 함수는 큐에서 제거된 I/O 작업이 없는 경우 FALSE를 반환합니다. 이는 일반적으로 이 호출에 대한 매개 변수를 처리하는 동안 오류가 발생했거나 CompletionPort 핸들이 닫혔거나 유효하지 않음을 의미합니다. GetLastError 함수는 확장 오류 정보를 제공합니다.

연결된 핸들이 닫혀 GetQueuedCompletionStatusEx에 대한 호출이 실패하면 함수는 FALSE를 반환하고 GetLastError는 ERROR_ABANDONED_WAIT_0을 반환합니다.

서버 애플리케이션에는 동일한 완료 포트에 대해 GetQueuedCompletionStatusEx 함수를 호출하는 여러 스레드가 있을 수 있습니다. I/O 작업이 완료되면 선입선출 순서로 이 포트에 대한 큐에 추가됩니다. 스레드가 이 호출에 대해 적극적으로 대기하는 경우 큐에 대기된 하나 이상의 요청은 해당 스레드에 대한 호출만 완료합니다.

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 Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	ioapiset.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll