| UINT SetTimer(hwnd, idTimer, uTimeout, tmprc) | |||||
| HWND hwnd; | /* handle of window for timer messages | */ | |||
| UINT idTimer; | /* timer identifier, */ | ||||
| UINT uTimeout; | /* time-out duration, */ | ||||
| TIMERPROC tmprc; | /* instance address of timer procedure | */ | |||
The SetTimer function installs a system timer. A time-out value is specified, and every time a time-out occurs, the system posts a WM_TIMER message to the installing application's message queue or passes the message to an application-defined TimerProc callback function.
hwnd
Identifies the window to be associated with the timer. If the tmprc parameter is NULL, the window procedure associated with this window receives the WM_TIMER messages generated by the timer. If this parameter is NULL, no window is associated with the timer.
idTimer
Specifies a nonzero timer identifier. If the hwnd parameter is NULL, this parameter is ignored.
uTimeout
Specifies the time-out value, in milliseconds.
tmprc
Specifies the procedure-instance address of the callback function that processes the WM_TIMER messages. If this parameter is NULL, the WM_TIMER messages are placed in the application's message queue and the hwnd member of the MSG structure contains the window handle specified in hwnd. For more information, see the description of the TimerProc callback function.
The MSG structure has the following form:
typedef struct tagMSG { /* msg */
HWND hwnd;
UINT message;
WPARAM wParam;
LPARAM lParam;
DWORD time;
POINT pt;
} MSG;For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.
The return value is the identifier of the new timer if hwnd is NULL and the function is successful. An application passes this value to the KillTimer function to kill the timer. The return value is nonzero if hwnd is a valid window handle and the function is successful. Otherwise, the return value is zero.
Timers are a limited global resource; therefore, it is important that an application check the value returned by the SetTimer function to verify that a timer is available.
The tmprc parameter must specify a procedure-instance address of the callback function, and the callback function must be exported in the application's module-definition file. A procedure-instance address can be created by using the MakeProcInstance function. The callback function must use the Pascal calling convention and must be declared as FAR.
The following example installs a system timer. The system will pass WM_TIMER messages generated by the timer to the “MyTimerProc” callback function.
TIMERPROC lpfnMyTimerProc;
lpfnMyTimerProc = (TIMERPROC) MakeProcInstance(MyTimerProc, hinst);
SetTimer(hwnd, ID_MYTIMER, 5000, lpfnMyTimerProc);