setTimer 函式 (winuser.h)

發行項
03/09/2024

使用指定的逾時值建立定時器。

語法

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

參數

[in, optional] hWnd

類型： HWND

要與定時器相關聯的視窗句柄。呼叫線程必須擁有此視窗。如果 hWnd 的 NULL 值與現有定時器的 nIDEvent 一起傳入，則會以現有的非 NULL hWnd 定時器相同的方式來取代該定時器。

[in] nIDEvent

類型： UINT_PTR

非零定時器標識碼。如果 hWnd 參數為 NULL，且 nIDEvent 與現有的定時器不符，則會忽略它，併產生新的定時器標識符。如果 hWnd 參數不是 NULL ，且 hWnd 指定的視窗已經有具有 nIDEvent 值的定時器，則現有的定時器會由新的定時器取代。當 SetTimer 取代定時器時，定時器就會重設。因此，訊息會在目前逾時值經過之後傳送，但會忽略先前設定的逾時值。如果呼叫不適合取代現有的定時器，則如果 hWnd 為 NULL，則 nIDEvent 應該是 0。

[in] uElapse

類型： UINT

逾時值 (以毫秒為單位)。

如果 uElapse 小於 USER_TIMER_MINIMUM (0x0000000A) ，則逾時會設定為 USER_TIMER_MINIMUM。如果 uElapse 大於 USER_TIMER_MAXIMUM (0x7FFFFFFF) ，則逾時會設定為 USER_TIMER_MAXIMUM。

[in, optional] lpTimerFunc

類型： TIMERPROC

當逾時值經過時，要通知函式的指標。如需函式的詳細資訊，請參閱 TimerProc。如果 lpTimerFunc 為 NULL，系統會將 WM_TIMER 訊息張貼至應用程式佇列。訊息 MSG 結構的 hwnd 成員包含 hWnd 參數的值。

傳回值

類型： UINT_PTR

如果函式成功且 hWnd 參數為 NULL，則傳回值是識別新定時器的整數。應用程式可以將此值傳遞至 KillTimer 函式，以終結定時器。

如果函式成功且 hWnd 參數不是 NULL，則傳回值為非零整數。應用程式可以將 nIDEvent 參數的值傳遞至 KillTimer 函式，以終結定時器。

如果函式無法建立定時器，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

應用程式可以在視窗程式中加入WM_TIMER case 語句，或在建立定時器時指定 TimerProc 回呼函式，來處理WM_TIMER訊息。當您指定 TimerProc 回呼函式時，DispatchMessage 會呼叫回呼函式，而不是在處理非 NULL lParam WM_TIMER 時呼叫視窗程式。因此，即使您使用 TimerProc 而不是處理 WM_TIMER，您也需要在呼叫線程中分派訊息。

WM_TIMER訊息的 wParam 參數包含 nIDEvent 參數的值。

定時器標識碼 nIDEvent 專屬於相關聯的視窗。另一個視窗可以有自己的定時器，其標識碼與另一個視窗所擁有的定時器相同。定時器是相異的。

當 hWnd 為 NULL 時，SetTimer 可以重複使用定時器識別碼。

使用 SetTimer 或其他定時器相關函式之前，建議透過 SetUserObjectInformationW 函式將UOI_TIMERPROC_EXCEPTION_SUPPRESSION旗標設定為 false，否則應用程式可能會發生無法預期的行為，而且可能會容易受到安全性攻擊。如需詳細資訊，請參閱 SetUserObjectInformationW。

範例

如需範例，請參閱建立定時器。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-window-l1-1-2 (於 Windows 10 10.0.10240 版)