Multimedia Timer Functions
The following functions are used with multimedia timers.
timeBeginPeriod
timeEndPeriod
timeGetDevCaps
timeGetSystemTime
timeGetTime
timeKillEvent
TimeProc
timeSetEvent
Timer Event Operations
After you have established your application's timer resolution, you can start timer events by using the timeSetEvent function. This function returns a timer identifier that can be used to stop or identify timer events. One of the function's parameters is the address of a TimeProc callback function that is called when the timer event takes place.
There are two types of timer events: single and periodic. A single timer event occurs once, after a specified number of milliseconds. A periodic timer event occurs every time a specified number of milliseconds elapses. The interval between periodic events is called an event delay. Periodic timer events with an event delay of 10 milliseconds or less consume a significant portion of CPU resources.
The relationship between the resolution of a timer event and the length of the event delay is important in timer events. For example, if you specify a resolution of 5 and an event delay of 100, the timer services notify the callback function after an interval ranging from 95 to 105 milliseconds.
You can cancel an active timer event at any time by using the timeKillEvent function. Be sure to cancel any outstanding timers before freeing the memory containing the callback function.
Note The multimedia timer runs in its own thread.
Obtaining and Setting Timer Resolution
The following example calls the timeGetDevCaps function to determine the minimum and maximum timer resolutions supported by the timer services. Before it sets up any timer events, the example establishes the minimum timer resolution by using the timeBeginPeriod function.
#define TARGET_RESOLUTION 1 // 1-millisecond target resolution
TIMECAPS tc;
UINT wTimerRes;
if (timeGetDevCaps(&tc, sizeof(TIMECAPS)) != TIMERR_NOERROR)
{
// Error; application can't continue.
}
wTimerRes = min(max(tc.wPeriodMin, TARGET_RESOLUTION), tc.wPeriodMax);
timeBeginPeriod(wTimerRes);
Starting a Single Timer Event
To start a single timer event, an application must call the timeSetEvent function, specifying the amount of time before the callback occurs, the resolution, the address of the callback function (see TimeProc), and the user data to supply with the callback function. An application can use a function like the following to start a single timer event.
UINT SetTimerCallback(NPSEQ npSeq, // sequencer data
UINT msInterval) // event interval
{
npSeq->wTimerID = timeSetEvent(
msInterval, // delay
wTimerRes, // resolution (global variable)
OneShotCallback, // callback function
(DWORD)npSeq, // user data
TIME_ONESHOT ); // single timer event
if(! npSeq->wTimerID)
return ERR_TIMER;
else
return ERR_NOERROR;
}
For an example of the callback function OneShotCallback, see Writing a Timer Callback Function.
Writing a Timer Callback Function
The following callback function, OneShotTimer, invalidates the identifier for the single timer event and calls a timer routine to handle the application-specific tasks. For more information, see TimeProc.
void CALLBACK OneShotTimer(UINT wTimerID, UINT msg,
DWORD dwUser, DWORD dw1, DWORD dw2)
{
NPSEQ npSeq; // pointer to sequencer data
npSeq = (NPSEQ)dwUser;
npSeq->wTimerID = 0; // invalidate timer ID (no longer in use)
TimerRoutine(npSeq); // handle tasks
}
Canceling a Timer Event
The application must cancel any outstanding timers by calling the timeKillEvent function before it frees the memory that contains the callback function. To cancel a timer event, it might call the following function.
void DestroyTimer(NPSEQ npSeq)
{
if(npSeq->wTimerID) { // is timer event pending?
timeKillEvent(npSeq->wTimerID); // cancel the event
npSeq->wTimerID = 0;
}
}
timeSetEvent
The timeSetEvent function starts a specified timer event. The multimedia timer runs in its own thread. After the event is activated, it calls the specified callback function or sets or pulses the specified event object.
MMRESULT timeSetEvent(
UINT uDelay,
UINT uResolution,
LPTIMECALLBACK lpTimeProc,
DWORD dwUser,
UINT fuEvent
);
Parameters
uDelay
Event delay, in milliseconds. If this value is not in the range of the minimum and maximum event delays supported by the timer, the function returns an error.
uResolution
Resolution of the timer event, in milliseconds. The resolution increases with smaller values; a resolution of 0 indicates periodic events should occur with the greatest possible accuracy. To reduce system overhead, however, you should use the maximum value appropriate for your application.
lpTimeProc
Address of a callback function that is called once upon expiration of a single event or periodically upon expiration of periodic events. If fuEvent specifies the TIME_CALLBACK_EVENT_SET or TIME_CALLBACK_EVENT_PULSE flag, then the lpTimeProc parameter is interpreted as a handle to an event object. The event will be set or pulsed upon completion of a single event or periodically upon completion of periodic events.
dwUser
User-supplied callback data.
fuEvent
Timer event type. This parameter may include one of the following values. Value Meaning
TIME_ONESHOT Event occurs once, after uDelay milliseconds.
TIME_PERIODIC Event occurs every uDelay milliseconds.
The fuEvent parameter may also include one of the following values: Value Meaning
TIME_CALLBACK_FUNCTION When the timer expires, Windows calls the function pointed to by the lpTimeProc parameter. This is the default.
TIME_CALLBACK_EVENT_SET When the timer expires, Windows calls theSetEvent function to set the event pointed to by the lpTimeProc parameter. The dwUser parameter is ignored.
TIME_CALLBACK_EVENT_PULSE When the timer expires, Windows calls thePulseEvent function to pulse the event pointed to by the lpTimeProc parameter. The dwUser parameter is ignored.
Return Values
Returns an identifier for the timer event if successful or an error otherwise. This function returns NULL if it fails and the timer event was not created. (This identifier is also passed to the callback function.)
Remarks
Each call to timeSetEvent for periodic timer events requires a corresponding call to the timeKillEvent function.
QuickInfo
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in mmsystem.h.
Import Library: Use winmm.lib.
See Also
Multimedia Timers Overview, Multimedia Timer Functions,PulseEvent,SetEvent, timeKillEvent
timeKillEvent
The timeKillEvent function cancels a specified timer event.
MMRESULT timeKillEvent(
UINT uTimerID
);
Parameters
uTimerID
Identifier of the timer event to cancel. This identifier was returned by the timeSetEvent function when the timer event was set up.
Return Values
Returns TIMERR_NOERROR if successful or MMSYSERR_INVALPARAM if the specified timer event does not exist.
QuickInfo
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in mmsystem.h.
Import Library: Use winmm.lib.
See Also
Multimedia Timers Overview, Multimedia Timer Functions, timeSetEvent