2008 December 11th Thursday

 The Multimedia time Functions

  When dealing with the multimedia timer, you specify two different times, both in milliseconds. The first is the delay time, and the second is called the resolution.
You can think of the resolution as a tolerable error. If you specify a delay of 100 milliseconds with a resolution of 10 milliseconds, the actual timer delay can range
anywhere from 90 to 110 milliseconds.

  Before you begin using the timer, you should obtain the timer device capabilities:

timeGetDevCaps (&timecaps, uSize) ;

  The first argument is a pointer to a structure of type TIMECAPS, and the second argument is the size of this structure. The TIMECAPS structure has only two fields,
wPeriodMin and wPeriodMax. These are the minimum and maximum resolution values supported by the timer device driver. If you look at these values after calling timeGetDevCaps,
you'll find that wPeriodMin is 1 and wPeriodMax is 65535, so this function may not seem crucial. However, it's a good idea to get these resolution values anyway and use
them in the other timer function calls.

The next step is to call

timeBeginPeriod (uResolution) ;

to indicate the lowest timer resolution value that your program requires. This value should be within the range given in the TIMECAPS structure. This call allows the timer
device driver to best provide for multiple programs that might be using the timer. Every call to timeBeginPeriod must be paired with a later call to timeEndPeriod, which
I'll describe shortly.

  Now you're ready to actually set a timer event:

idTimer = timeSetEvent (uDelay, uResolution, CallBackFunc, dwData, uFlag) ;

  The idTimer returned from the call will be zero if an error occurs. Following this call, the function CallBackFunc will be called from Windows in uDelay milliseconds with
an allowable error specified by uResolution. The uResolution value must be greater than or equal to the resolution value passed to timeBeginPeriod. The dwData parameter is
program-defined data later passed to CallBackFunc. The last parameter can be either TIME_ONESHOT to get a single call to CallBackFunc in uDelay number of milliseconds or
TIME_PERIODIC to get calls to CallBackFunc every uDelay milliseconds.

  To stop a one-shot timer event before CallBackFunc is called, or to halt periodic timer events, call

timeKillEvent (idTimer) ;

  You don't need to kill a one-shot timer event after CallBackFunc is called. When you're finished using the timer in your program, call

timeEndPeriod (wResolution) ;

with the same argument passed to timeBeginPeriod.

  Two other functions begin with the prefix time. The function

dwSysTime = timeGetTime () ;

returns the system time in milliseconds since Windows first started up. The function

timeGetSystemTime (&mmtime, uSize) ;

  requires a pointer to an MMTIME structure as the first argument and the size of this structure as the second. Although the MMTIME structure can be used in other circumstances
to get the system time in formats other than milliseconds, in this case it always returns the time in milliseconds. So, timeGetSystemTime is superfluous.

  The callback function is limited in the Windows function calls it can make. The callback function can call PostMessage, four timer functions (timeSetEvent, timeKillEvent,
timeGetTime, and the superfluous timeGetSystemTime), two MIDI output functions (midiOutShortMsg and midiOutLongMsg), and the debugging function OutputDebugStr.

  Obviously, the multimedia timer is designed specifically for playing MIDI sequences and has very limited use for anything else. You can, of course, use PostMessage for informing
a window procedure of timer events, and the window procedure can do whatever it likes, but it won't be responding with the accuracy of the timer callback itself.

  The callback function has five parameters, but only two of them are used: the timer ID number returned from timeSetEvent and the dwData value originally passed as an argument
to timeSetEvent.