SetCoalescableTimer 함수(winuser.h)

아티클
08/28/2023

지정된 시간 제한 값과 병합 허용 오차 지연을 사용하여 타이머를 만듭니다.

구문

UINT_PTR SetCoalescableTimer(
  [in, optional] HWND      hWnd,
  [in]           UINT_PTR  nIDEvent,
  [in]           UINT      uElapse,
  [in, optional] TIMERPROC lpTimerFunc,
  [in]           ULONG     uToleranceDelay
);

매개 변수

[in, optional] hWnd

형식: HWND

타이머와 연결할 창에 대한 핸들입니다. 이 창은 호출 스레드가 소유해야 합니다. hWnd에 대한 NULL 값이 기존 타이머의 nIDEvent와 함께 전달되는 경우 해당 타이머는 기존 NULL이 아닌 hWnd 타이머와 동일한 방식으로 대체됩니다.

[in] nIDEvent

형식: UINT_PTR

타이머 식별자입니다. hWnd 매개 변수가 NULL이고 nIDEvent가 기존 타이머와 일치하지 않으면 nIDEvent가 무시되고 새 타이머 ID가 생성됩니다. hWnd 매개 변수가 NULL이 아니고 hWnd로 지정된 창에 nIDEvent 값이 있는 타이머가 이미 있는 경우 기존 타이머가 새 타이머로 대체됩니다. SetCoalescableTimer가 타이머를 대체하면 타이머가 다시 설정됩니다. 따라서 현재 제한 시간 값이 경과한 후 메시지가 전송되지만 이전에 설정한 제한 시간 값은 무시됩니다. 호출이 기존 타이머를 대체하지 않는 경우 hWnd가 NULL인 경우 nIDEvent는 0이어야 합니다.

[in] uElapse

형식: UINT

제한 시간 값(밀리초)입니다.

uElapse가 USER_TIMER_MINIMUM(0x0000000A) 미만이면 시간 제한이 USER_TIMER_MINIMUM 설정됩니다. uElapse가 USER_TIMER_MAXIMUM(0x7FFFFFFF)보다 크면 시간 제한이 USER_TIMER_MAXIMUM 설정됩니다.

uElapse 및 uToleranceDelay의 합계가 USER_TIMER_MAXIMUM 초과하면 ERROR_INVALID_PARAMETER 예외가 발생합니다.

[in, optional] lpTimerFunc

형식: TIMERPROC

제한 시간 값이 경과할 때 알림을 받을 함수에 대한 포인터입니다. 함수에 대한 자세한 내용은 TimerProc을 참조하세요. lpTimerFunc가 NULL인 경우 시스템은 애플리케이션 큐에 WM_TIMER 메시지를 게시합니다. 메시지 MSG 구조의 hwnd 멤버에는 hWnd 매개 변수의 값이 포함됩니다.

[in] uToleranceDelay

형식: ULONG

다음 값 중 하나일 수 있습니다.

값	의미
TIMERV_DEFAULT_COALESCING 0x00000000	시스템 기본 타이머 병합을 사용합니다.
TIMERV_NO_COALESCING 0xFFFFFFFF	타이머 병합을 사용하지 않습니다. 이 값을 사용하면 시스템 기본 타이머 병합 또는 애플리케이션 호환성 플래그에 관계없이 생성된 타이머가 병합되지 않습니다. 참고 타이머에 병합이 필요하지 않은 경우 이 값을 사용하지 마세요.
0x1 - 0x7FFFFFF5	병합 허용 오차 지연(밀리초)을 지정합니다. 애플리케이션은 이 값을 시스템 기본값(TIMERV_DEFAULT_COALESCING) 또는 가능한 가장 큰 값으로 설정해야 합니다. uElapse 및 uToleranceDelay의 합계가 USER_TIMER_MAXIMUM(0x7FFFFFFF)를 초과하면 ERROR_INVALID_PARAMETER 예외가 발생합니다. 자세한 내용 및 모범 사례는 Windows 타이머 병합 을 참조하세요.
다른 모든 값	잘못된 값입니다. uToleranceDelay가 잘못된 값으로 설정된 경우 함수는 실패하고 0을 반환합니다.

반환 값

형식: UINT_PTR

함수가 성공하고 hWnd 매개 변수가 NULL이면 반환 값은 새 타이머를 식별하는 정수입니다. 애플리케이션은 이 값을 KillTimer 함수에 전달하여 타이머를 삭제할 수 있습니다.

함수가 성공하고 hWnd 매개 변수가 NULL이 아닌 경우 반환 값은 0이 아닌 정수입니다. 애플리케이션은 nIDEvent 매개 변수의 값을 KillTimer 함수에 전달하여 타이머를 삭제할 수 있습니다.

함수가 타이머를 만들지 못하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

애플리케이션은 창 프로시저에 WM_TIMER 사례 문을 포함하거나 타이머를 만들 때 TimerProc 콜백 함수를 지정하여 WM_TIMER 메시지를 처리할 수 있습니다. TimerProc 콜백 함수를 지정하면 기본 창 프로시저는 WM_TIMER 처리할 때 콜백 함수를 호출합니다. 따라서 WM_TIMER 처리하는 대신TimerProc을 사용하는 경우에도 호출 스레드에서 메시지를 디스패치해야 합니다.

WM_TIMER 메시지의 wParam 매개 변수에는 nIDEvent 매개 변수의 값이 포함됩니다.

타이머 식별자 nIDEvent는 연결된 창과 관련이 있습니다. 다른 창에는 다른 창이 소유한 타이머와 동일한 식별자가 있는 자체 타이머가 있을 수 있습니다. 타이머는 고유합니다.

SetTimer는hWnd 가 NULL인 경우 타이머 ID를 다시 사용할 수 있습니다.

uToleranceDelay를 0으로 설정하면 시스템 기본 타이머 병합이 사용되고 SetCoalescableTimer이 SetTimer와 동일하게 작동합니다.

SetCoalescableTimer 또는 기타 타이머 관련 함수를 사용하기 전에 SetUserObjectInformationW 함수를 통해 UOI_TIMERPROC_EXCEPTION_SUPPRESSION 플래그를 false로 설정하는 것이 좋습니다. 그렇지 않으면 애플리케이션이 예측할 수 없이 동작하고 보안 악용에 취약할 수 있습니다. 자세한 내용은 SetUserObjectInformationW를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 8 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2012 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winuser.h(Windows.h 포함)
라이브러리	User32.lib
DLL	User32.dll
API 세트	ext-ms-win-ntuser-window-l1-1-2(Windows 10 버전 10.0.10240에 도입됨)