SetThreadpoolTimerEx 함수(threadpoolapiset.h)

아티클
03/08/2023

타이머 개체를 설정하여 이전 타이머(있는 경우)를 대체합니다. 작업자 스레드는 지정된 시간 제한이 만료된 후 타이머 개체의 콜백을 호출합니다.

구문

BOOL SetThreadpoolTimerEx(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in, optional] DWORD     msWindowLength
);

매개 변수

[in, out] pti

설정할 타이머 개체를 정의하는 TP_TIMER 구조체에 대한 포인터입니다. CreateThreadpoolTimer 함수는 이 포인터를 반환합니다.

[in, optional] pftDueTime

타이머가 만료되어야 하는 절대 또는 상대 시간을 지정하는 FILETIME 구조체에 대한 포인터입니다. 이 매개 변수가 양수 값을 가리키는 경우 100나노초 단위로 측정된 1601년 1월 1일(UTC) 이후의 절대 시간을 나타냅니다. 이 매개 변수가 음수 값을 가리키는 경우 현재 시간을 기준으로 대기할 시간을 나타냅니다. 이 매개 변수가 0을 가리키면 타이머가 즉시 만료됩니다. 시간 값에 대한 자세한 내용은 파일 시간을 참조하세요.

이 매개 변수가 NULL인 경우 타이머 개체는 새 콜백 큐를 중단합니다(하지만 이미 큐에 대기 중인 콜백은 계속 발생).

pftDueTime 매개 변수가 NULL이 아닌 경우 타이머가 설정됩니다.

[in] msPeriod

타이머 기간(밀리초)입니다. 이 매개 변수가 0이면 타이머에 한 번 신호가 전송됩니다. 이 매개 변수가 0보다 크면 타이머가 주기적입니다. 주기적 타이머는 타이머가 취소될 때까지 기간이 경과할 때마다 자동으로 다시 활성화됩니다.

[in, optional] msWindowLength

시스템이 타이머 콜백을 호출하기 전에 지연할 수 있는 최대 시간입니다. 이 매개 변수를 설정하면 시스템에서 호출을 일괄 처리하여 전원을 절약할 수 있습니다.

반환 값

타이머가 이전에 설정되었고 취소된 경우 TRUE를 반환합니다. 그렇지 않으면 FALSE를 반환합니다.

타이머의 이전 상태가 "set"이고 함수가 FALSE를 반환하는 경우 콜백이 진행 중이거나 시작하려고 합니다. 자세한 내용은 설명을 참조하세요.

설명

타이머를 설정하면 이전 타이머(있는 경우)가 취소됩니다.

경우에 따라 애플리케이션이 스레드 풀 타이머를 닫은 후 콜백 함수가 실행될 수 있습니다. 이 동작을 방지하려면 애플리케이션이 CloseThreadpoolTimer에 설명된 단계를 따라야 합니다.

pftDueTime에 지정된 기한이 상대적인 경우 시스템이 절전 모드 또는 최대 절전 모드에서 보내는 시간은 타이머 만료에 포함되지 않습니다. 시스템에서 절전 모드 해제 상태에서 보내는 누적 경과 시간이 타이머의 상대 기한 또는 기간과 같으면 타이머가 신호를 보냅니다. pftDueTime으로 지정된 기한이 절대인 경우 시스템이 절전 모드 또는 최대 절전 모드에서 보내는 시간은 타이머 만료에 포함됩니다. 시스템이 절전 모드인 동안 타이머가 만료되면 시스템이 절전 모드 해제될 때 타이머가 즉시 신호를 보냅니다.

이 함수를 사용하는 애플리케이션을 컴파일하려면 _WIN32_WINNT 0x0600 이상으로 정의합니다.

예제

예제는 스레드 풀 함수 사용을 참조하세요.

요구 사항

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