SetWaitableTimer 함수(synchapi.h)

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

통사론

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 기반 시간에 대한 자세한 내용은 시스템 시간참조하세요.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 및 Windows Server 2008 R2: 상대 시간이 지정된 경우 타이머에는 저전력 상태에서 소요된 시간이 포함됩니다. 예를 들어 컴퓨터가 절전 모드인 동안 타이머는 계속 카운트다운됩니다.

Windows 8 이상 Windows Server 2012 이상: 상대 시간이 지정된 경우 타이머에는 저전력 상태에서 소요된 시간이 포함되지 않습니다. 예를 들어 컴퓨터가 절전 모드인 동안 타이머는 계속 카운트다운되지 않습니다.

[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참조하세요. 시스템이 스레드 풀 스레드의 수명을 제어하므로 알림이 전달되기 전에 스레드를 종료할 수 있으므로 API는 스레드 풀 스레드에 대한 다른 신호 메커니즘뿐만 아니라 작동하지 않습니다. 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사용하는 예제는 대기 가능한 타이머 개체사용하는 참조하세요.

요구 사항

참고 항목

CancelWaitableTimer

CreateWaitableTimer

OpenWaitableTimer

동기화 함수

timerAPCProc

대기 가능한 타이머 개체