WaitForSingleObjectEx 함수(synchapi.h)
지정된 개체가 신호 상태, I/O 완료 루틴 또는 APC(비동기 프로시저 호출)가 스레드에 큐에 대기하거나 시간 제한 간격이 경과할 때까지 기다립니다.
여러 개체를 기다리려면 WaitForMultipleObjectsEx를 사용합니다.
구문
DWORD WaitForSingleObjectEx(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
매개 변수
[in] hHandle
개체에 대한 핸들입니다. 핸들을 지정할 수 있는 개체 형식 목록은 다음 주의 섹션을 참조하세요.
대기가 보류 중인 동안 이 핸들이 닫히면 함수의 동작이 정의되지 않습니다.
핸들에 SYNCHRONIZE 액세스 권한이 있어야 합니다. 자세한 내용은 표준 액세스 권한을 참조하세요.
[in] dwMilliseconds
제한 시간 간격(밀리초)입니다. 0이 아닌 값을 지정하면 함수는 개체가 신호를 받으면 I/O 완료 루틴 또는 APC가 큐에 대기하거나 간격이 경과할 때까지 대기합니다. dwMilliseconds가 0이면 조건이 충족되지 않으면 함수가 대기 상태로 들어가지 않습니다. 항상 즉시 반환됩니다. 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가 큐에 추가됩니다.
반환 값
함수가 성공하면 반환 값은 함수가 반환되도록 한 이벤트를 나타냅니다. 다음 값 중 하나일 수 있습니다.
반환 코드/값 | 설명 |
---|---|
|
지정된 개체는 소유 스레드가 종료되기 전에 뮤텍스 개체를 소유한 스레드에서 해제되지 않은 뮤텍스 개체입니다. 뮤텍스 개체의 소유권은 호출 스레드에 부여되고 뮤텍스는 서명되지 않은 것으로 설정됩니다.
뮤텍스가 영구 상태 정보를 보호하는 경우 일관성을 위해 검사 합니다. |
|
스레드에 큐에 대기 중인 하나 이상의 사용자 모드 APC( 비동기 프로시저 호출 )로 대기가 종료되었습니다. |
|
지정된 개체의 상태가 신호를 보냅니다. |
|
시간 제한 간격이 경과하고 개체의 상태는 서명되지 않습니다. |
|
함수가 실패했습니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. |
설명
WaitForSingleObjectEx 함수는 대기 조건이 충족되었는지 여부를 결정합니다. 조건이 충족되지 않으면 대기 조건의 조건이 충족되거나 시간 제한 간격이 경과할 때까지 호출 스레드가 대기 상태가 됩니다.
함수는 일부 유형의 동기화 개체의 상태를 수정합니다. 수정은 신호 상태가 함수를 반환하게 한 개체에 대해서만 발생합니다. 예를 들어 세마포 개체의 개수가 1씩 감소합니다.
WaitForSingleObjectEx 함수는 다음 개체를 기다릴 수 있습니다.
- 변경 알림
- 콘솔 입력
- 이벤트
- 메모리 리소스 알림
- Mutex
- 프로세스
- 세마포
- 스레드
- 대기 가능한 타이머
예제
예제는 완료 루틴을 사용하여 명명된 파이프 서버를 참조하세요.
요구 사항
요구 사항 | 값 |
---|---|
지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
대상 플랫폼 | Windows |
헤더 | synchapi.h(Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2에 Windows.h 포함) |
라이브러리 | Kernel32.lib |
DLL | Kernel32.dll |
참고 항목
피드백
https://aka.ms/ContentUserFeedback
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요.다음에 대한 사용자 의견 제출 및 보기