SetWaitableTimer 함수(synchapi.h)

아티클
03/08/2023

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

구문

BOOL SetWaitableTimer(
  [in]           HANDLE              hTimer,
  [in]           const LARGE_INTEGER *lpDueTime,
  [in]           LONG                lPeriod,
  [in, optional] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in, optional] LPVOID              lpArgToCompletionRoutine,
  [in]           BOOL                fResume
);

매개 변수

[in] hTimer

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

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

[in] lpDueTime

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

[in] lPeriod

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

[in, optional] pfnCompletionRoutine

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

[in, optional] lpArgToCompletionRoutine

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

[in] fResume

이 매개 변수가 TRUE이면 타이머 상태가 신호로 설정되면 시스템이 일시 중단된 전원 보존 모드로 복원됩니다. 그렇지 않으면 시스템이 복원되지 않습니다. 시스템에서 복원을 지원하지 않으면 호출이 성공하지만 GetLastError 는 ERROR_NOT_SUPPORTED 반환합니다.

반환 값

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

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

설명

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

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

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

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

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

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

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

타이머를 처리하는 API는 다양한 하드웨어 클록을 사용합니다. 이러한 클록은 예상과 크게 다른 해상도를 가질 수 있습니다. 일부는 밀리초(RTC 기반 타이머 칩을 사용하는 경우)에서 나노초 단위로 측정된 값(ACPI 또는 TSC 카운터를 사용하는 경우)으로 측정될 수 있습니다. timeBeginPeriod 및 timeEndPeriod 함수를 호출하여 API의 해상도를 변경할 수 있습니다. 해상도를 변경할 수 있는 정확한 방법은 특정 API에서 사용하는 하드웨어 클록에 따라 달라집니다. 자세한 내용은 하드웨어 설명서를 검사.

예제

SetWaitableTimer를 사용하는 예제는 대기 가능한 타이머 개체 사용을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	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