SetWaitableTimerEx 함수(synchapi.h)

지정된 대기 가능 타이머를 활성화하고 타이머에 대한 컨텍스트 정보를 제공합니다. 기한이 되면 타이머가 신호를 받고 타이머를 설정하는 스레드는 선택적 완료 루틴을 호출합니다.

구문

BOOL SetWaitableTimerEx(
  [in] HANDLE              hTimer,
  [in] const LARGE_INTEGER *lpDueTime,
  [in] LONG                lPeriod,
  [in] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in] LPVOID              lpArgToCompletionRoutine,
  [in] PREASON_CONTEXT     WakeContext,
  [in] ULONG               TolerableDelay
);

매개 변수

[in] hTimer

타이머 개체에 대한 핸들입니다. CreateWaitableTimer 또는 OpenWaitableTimer 함수는 이 핸들을 반환합니다.

핸들에 TIMER_MODIFY_STATE 액세스 권한이 있어야 합니다. 자세한 내용은 동기화 개체 보안 및 액세스 권한을 참조하세요.

[in] lpDueTime

타이머의 상태가 100나노초 간격으로 신호로 설정되는 시간입니다. FILETIME 구조에 설명된 형식을 사용합니다. 양수 값은 절대 시간을 나타냅니다. 시스템이 내부적으로 UTC 기반 시간을 사용하므로 UTC 기반 절대 시간을 사용해야 합니다. 음수 값은 상대 시간을 나타냅니다. 실제 타이머 정확도는 하드웨어의 기능에 따라 달라집니다. UTC 기반 시간에 대한 자세한 내용은 시스템 시간을 참조하세요.

[in] lPeriod

타이머 기간(밀리초)입니다. lPeriod가 0이면 타이머에 한 번 신호가 전송됩니다. lPeriod가 0보다 크면 타이머가 주기적입니다. CancelWaitableTimer 함수를 사용하여 타이머가 취소되거나 SetWaitableTimerEx를 사용하여 다시 설정될 때까지 주기적 타이머는 기간이 경과할 때마다 자동으로 다시 활성화됩니다. lPeriod가 0보다 작으면 함수가 실패합니다.

[in] pfnCompletionRoutine

선택적 완료 루틴에 대한 포인터입니다. 완료 루틴은 타이머가 신호를 받을 때 실행할 PTIMERAPCROUTINE 형식의 애플리케이션 정의 함수입니다. 타이머 콜백 함수에 대한 자세한 내용은 TimerAPCProc을 참조하세요. APC 및 스레드 풀 스레드에 대한 자세한 내용은 비고를 참조하세요.

[in] lpArgToCompletionRoutine

완료 루틴에 전달되는 구조체에 대한 포인터입니다.

[in] WakeContext

타이머에 대한 컨텍스트 정보를 포함하는 REASON_CONTEXT 구조체에 대한 포인터입니다.

[in] TolerableDelay

만료 시간에 허용되는 지연 시간(밀리초)입니다.

반환 값

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

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

SetWaitableTimerEx 함수는 SetWaitableTimer 함수와 유사합니다. 단, SetWaitableTimerEx를 사용하여 컨텍스트 문자열과 타이머 만료 지연을 지정할 수 있습니다.

이 함수를 사용하는 애플리케이션을 컴파일하려면 _WIN32_WINNT 0x0601 이상으로 정의합니다. 자세한 내용은 Windows 헤더 사용을 참조하세요.

타이머는 처음에 비활성 상태입니다. 타이머를 활성화하려면 SetWaitableTimerEx를 호출합니다. SetWaitableTimerEx를 호출할 때 타이머가 이미 활성 상태이면 타이머가 중지된 다음 다시 활성화됩니다. 이러한 방식으로 타이머를 중지해도 타이머 상태가 신호로 설정되지 않으므로 타이머의 대기 작업에서 차단된 스레드는 차단된 상태로 유지됩니다. 그러나 보류 중인 완료 루틴을 취소합니다.

지정된 기한이 도착하면 타이머가 비활성 상태가 되고 선택적 APC는 미해결 APC가 이미 큐에 대기 중인 경우 타이머를 설정하는 스레드에 큐에 대기합니다. 타이머의 상태가 신호로 설정되고, 지정된 기간을 사용하여 타이머가 다시 활성화되고, 타이머를 설정하는 스레드는 경고 대기 상태가 되면 완료 루틴을 호출합니다. 자세한 내용은 QueueUserAPC를 참조하세요. 시스템이 스레드 풀 스레드의 수명을 제어하므로 알림이 전달되기 전에 스레드가 종료될 수 있으므로 APC는 스레드 풀 스레드에 대한 다른 신호 메커니즘뿐만 아니라 작동하지 않습니다. pfnCompletionRoutine 매개 변수 또는 다른 APC 기반 신호 메커니즘을 사용하는 대신 CreateThreadpoolTimer로 만든 타이머와 같은 대기 가능한 개체를 사용합니다. I/O의 경우 CreateThreadpoolIo로 만든 I/O 완성 개체 또는 이벤트를 SetThreadpoolWait 함수에 전달할 수 있는 hEvent 기반 OVERLAPPED 구조를 사용합니다.

타이머를 설정하는 스레드가 종료되고 연결된 완료 루틴이 있는 경우 타이머가 취소됩니다. 그러나 타이머의 상태는 변경되지 않은 상태로 유지됩니다. 완료 루틴이 없으면 스레드를 종료해도 타이머에 영향을 주지 않습니다.

수동 재설정 타이머가 신호 상태로 설정된 경우 타이머를 다시 설정하기 위해 SetWaitableTimerEx 가 호출될 때까지 이 상태로 유지됩니다. 따라서 초기 기한이 도착하면 주기적인 수동 재설정 타이머가 신호 상태로 설정되고 다시 설정될 때까지 신호를 유지합니다. 동기화 타이머가 신호 상태로 설정되면 스레드가 타이머 개체에 대한 대기 작업을 완료할 때까지 이 상태로 유지됩니다.

시스템 시간이 조정되면 미해결 절대 타이머의 기한이 조정됩니다.

SetWaitableTimerEx라는 스레드가 종료되면 타이머가 취소됩니다. 이렇게 하면 타이머가 신호 상태로 설정되기 전에 중지되고 미해결 APC가 취소됩니다. 타이머의 신호 상태를 변경하지 않습니다.

타이머를 사용하여 창에 대한 이벤트를 예약하려면 SetTimer 함수를 사용합니다.

요구 사항

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

참고 항목

REASON_CONTEXT

SetWaitableTimer