GetOverlappedResultEx 함수(ioapiset.h)

아티클
02/26/2024

지정된 시간 제한 간격 내에서 지정된 파일, 명명된 파이프 또는 통신 디바이스에서 겹치는 작업의 결과를 검색합니다. 호출 스레드는 경고 대기를 수행할 수 있습니다.

구문

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

매개 변수

[in] hFile

파일, 명명된 파이프 또는 통신 디바이스에 대한 핸들입니다. 이는 ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl 또는 WaitCommEvent 함수를 호출하여 겹치는 작업을 시작할 때 지정한 것과 동일한 핸들입니다.

[in] lpOverlapped

겹치는 작업이 시작될 때 지정된 OVERLAPPED 구조체에 대한 포인터입니다.

[out] lpNumberOfBytesTransferred

읽기 또는 쓰기 작업으로 실제로 전송된 바이트 수를 수신하는 변수에 대한 포인터입니다. TransactNamedPipe 작업의 경우 파이프에서 읽은 바이트 수입니다. DeviceIoControl 작업의 경우 디바이스 드라이버에서 반환하는 출력 데이터의 바이트 수입니다. ConnectNamedPipe 또는 WaitCommEvent 작업의 경우 이 값은 정의되지 않습니다.

[in] dwMilliseconds

제한 시간 간격(밀리초)입니다.

dwMilliseconds가 0이고 작업이 계속 진행 중인 경우 함수는 즉시 반환되고 GetLastError 함수는 ERROR_IO_INCOMPLETE 반환합니다.

dwMilliseconds가 0이 아니고 작업이 계속 진행 중인 경우 함수는 개체가 신호를 받을 때까지 대기하거나, I/O 완료 루틴 또는 APC가 큐에 대기되거나, 반환하기 전에 간격이 경과할 때까지 기다립니다. GetLastError를 사용하여 확장된 오류 정보를 가져옵니다.

dwMilliseconds가 INFINITE인 경우 함수는 개체가 신호를 받으면 또는 I/O 완료 루틴 또는 APC가 큐에 대기된 경우에만 를 반환합니다.

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] bAlertable

이 매개 변수가 TRUE 이고 호출 스레드가 대기 상태이면 시스템에서 I/O 완료 루틴 또는 APC를 큐에 대기할 때 함수가 반환됩니다. 그런 다음 호출 스레드는 루틴 또는 함수를 실행합니다. 그렇지 않으면 함수가 반환되지 않고 완료 루틴 또는 APC 함수가 실행되지 않습니다.

완료 루틴은 지정된 ReadFileEx 또는 WriteFileEx 함수가 완료되면 큐에 대기됩니다. 함수가 를 반환하고 완료 루틴은 bAlertable 이 TRUE이고 호출 스레드가 읽기 또는 쓰기 작업을 시작한 스레드인 경우에만 호출됩니다. QueueUserAPC를 호출하면 APC가 큐에 추가됩니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. 일반적인 오류 코드에는 다음이 포함됩니다.

dwMilliseconds가 0이고 작업이 계속 진행 중인 경우 GetLastError는 ERROR_IO_INCOMPLETE 반환합니다.
dwMilliseconds가 0이 아니고 I/O 완료 루틴 또는 APC가 대기 중인 경우 GetLastError는 WAIT_IO_COMPLETION 반환합니다.
dwMilliseconds가 0이 아니고 지정된 시간 제한 간격이 경과하면 GetLastError는 WAIT_TIMEOUT 반환합니다.

설명

GetOverlappedResultEx 함수는 다음과 같은 방법으로 GetOverlappedResult와 다릅니다. dwMilliseconds 매개 변수는 작업에 대한 시간 제한 간격을 지정할 수 있으며 bAlertable 매개 변수는 호출 스레드가 경고 대기를 수행해야 한다고 지정할 수 있습니다.

GetOverlappedResultEx 함수에서 보고한 결과는 지정된 OVERLAPPED 구조가 제공된 지정된 핸들의 마지막 겹침 작업과 작업의 결과가 보류 중인 결과입니다. 작업을 시작한 함수가 FALSE를 반환하고 GetLastError 함수가 ERROR_IO_PENDING 반환할 때 보류 중인 작업이 표시됩니다. I/O 작업이 보류 중인 경우 작업을 시작한 함수는 OVERLAPPED 구조체의 hEvent 멤버를 서명되지 않은 상태로 다시 설정합니다. 그런 다음 보류 중인 작업이 완료되면 시스템에서 이벤트 개체를 신호 상태로 설정합니다.

OVERLAPPED 구조체에서 수동 재설정 이벤트 개체를 지정합니다. 자동 재설정 이벤트 개체를 사용하는 경우 겹치는 작업을 시작하고 GetOverlappedResultEx를 호출하는 간격으로 다른 대기 작업에서 이벤트 핸들을 지정해서는 안 됩니다. 예를 들어 이벤트 개체는 작업의 완료를 기다리는 대기 함수 중 하나에 지정되는 경우가 있습니다. 대기 함수가 반환되면 시스템은 자동 재설정 이벤트의 상태를 부호 없는 상태로 설정하고 dwMilliseconds 매개 변수가 INFINITE로 설정된 GetOverlappedResultEx에 대한 후속 호출로 인해 함수가 무기한 차단됩니다.

OVERLAPPED 구조체의 hEvent 멤버가 NULL인 경우 시스템은 hFile 핸들의 상태를 사용하여 작업이 완료되었을 때 신호를 보냅니다. 이 목적을 위해 파일, 명명된 파이프 또는 통신 디바이스 핸들을 사용하는 것은 권장되지 않습니다. 동일한 파일, 명명된 파이프 또는 통신 디바이스에서 여러 동시 겹치는 작업을 수행할 때 발생할 수 있는 혼동 때문에 이벤트 개체를 사용하는 것이 안전합니다. 이 상황에서는 어떤 연산으로 인해 개체의 상태가 신호를 받을지 알 수 없습니다.

요구 사항

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