Waitable Timers
Windows NT supports waitable timers, a type of waitable kernel object.You can always create your own timing signal by creating a timing thread that sets an event after waking from a Sleep call. serverNP (Program 11-3) also uses a timing thread to broadcast its pipe name periodically. Therefore, waitable timers are a redundant but useful way to perform tasks periodically or at specified times. In particular, a waitable timer can be set to signal at a specified absolute time.A waitable timer can be either a synchronization timer or a manual-reset notification timer. A synchronization timer is associated with a callback function, similar to an extended I/O completion routine, whereas a wait function is used to synchronize on a manual-reset notification timer.The first step is to create a timer handle with CreateWaitableTimer.
HANDLE CreateWaitableTimer (
LPSECURITY_ATTRIBUTES lpTimerAttributes,
BOOL bManualReset,
LPCTSTR lpTimerName);
The second parameter, bManualReset, determines whether the timer is a synchronization timer or a manual-reset notification timer. Program 14-3 uses a synchronization timer, but you can change the comment and the parameter setting to obtain a notification timer. Notice that there is also an OpenWaitableTimer function that can use the optional name supplied in the third argument.The timer is initially inactive, but SetWaitableTimer activates it and specifies the initial signal time and the time between periodic signals.
BOOL SetWaitableTimer (
HANDLE hTimer,
const LARGE_INTEGER *pDueTime,
LONG lPeriod,
PTIMERAPCROUTINE pfnCompletionRoutine,
LPVOID lpArgToCompletionRoutine,
BOOL fResume);
hTimer is a valid timer handle created using CreateWaitableTimer.The second parameter, pointed to by pDueTime, is either a positive absolute time or a negative relative time and is actually expressed as a FILETIME with a resolution of 100 nanoseconds. FILETIME variables were introduced in Chapter 3 and were used in Chapter 6's timep (Program 6-2).The interval between signals is specified in the third parameter, but in millisecond units. If this value is 0, the timer is signaled only once. A positive value indicates that the timer is a periodic timer and continues signaling periodically until you call CancelWaitableTimer. Negative interval values are not allowed.Program 14-3 on the book's Web site allows you to experiment with using the four combinations of the two timer types and with choosing between using a completion routine or waiting on the timer handle.The final parameter, fResume, is concerned with power conservation. See the documentation for more information.Use CancelWaitableTimer to cancel the last effect of a previous SetWaitableTimer, although it will not change the signaled state of the timer. Use another SetWaitableTimer call to do that.