Starting Timer Events

To initialize and start timer events, use the timeSetEvent function. This function returns a timer ID that can be used to stop or identify timer events. The timeSetEvent function has the following syntax:

WORD timeSetEvent(wDelay, wResolution, lpFunction, dwUser, wFlags)

The wDelay parameter specifies the period, in milliseconds, for timer events. If this value is less than the minimum timer period or greater than the maximum period, timeSetEvent fails.

The wResolution value establishes the accuracy of the timer event. The accuracy of the timer event can increase with smaller wResolution values. For example, on a one-time event with a wResolution value of 5 and a wDelay value of 100, the timer services notify your callback function after an interval ranging from 95 to 105 milliseconds. The application must have called timeBeginPeriod to specify a minimum resolution of 5 milliseconds.

Larger wResolution values provide flexibility to reduce the number of timer interrupts, which can seriously affect system performance. To reduce system overhead, use the maximum wResolution value appropriate for your application. To ensure that periodic events occur at specified intervals, use a resolution of zero.

Pass the name of the callback function in the lpFunction parameter, and pass any instance data in the dwUser parameter. The callback function must reside in a DLL, so you don't need to call MakeProcInstance to get the procedure-instance address of the callback function.

The wFlags parameter takes one of the following flags:

The timeSetEvent function returns a timer ID if successful or NULL if unsuccessful. Interrupt timers are a scarce resource, and periodic timers with resolution less than 100 milliseconds consume a significant portion of CPU time. For periodic timers, you must pair calls to timeSetEvent with calls to timeKillEvent. For more information, see the following section, “Canceling a Timer Event.”

The lpFunction parameter contains the procedure-instance address of the function to be called when the timer event takes place.

Since the callback function is accessed at interrupt time, it must adhere to strict programming guidelines. Timer-callback functions follow the same programming guidelines as callback functions for the low-level audio services. See “Using a Callback Function to Process Driver Messages” in Chapter 5, “Low-Level Audio Services,” for information on writing an interrupt callback function.

The timer-event callback function must have the following syntax:

void FAR PASCAL TimerCallback(
    WORD idTimer,                       // Timer ID
    WORD msg,                           // Not used
    DWORD dwUser,                       // User-instance data
    DWORD dw1,                          // Not used
    DWORD dw2 )                         // Not used

The idTimer parameter receives the timer ID, and the dwUser parameter receives the user-instance data passed to the timeSetEvent function. The msg, dw1, and dw2 parameters are not used.