NdisMCancelTimer

NdisMCancelTimer

VOID
   NdisMCancelTimer(
       IN PNDIS_MINIPORT_TIMER Timer,
       OUT PBOOLEAN TimerCancelled
       );

NdisMCancelTimer cancels a preceding call to NdisMSetPeriodicTimer or cancels the immediately preceding call to NdisMSetTimer if the interval given to NdisMSetTimer has not yet expired.

Parameters

Timer

Points to a timer object, already initialized with NdisMInitializeTimer and set with NdisMSetPeriodicTimer or NdisMSetTimer.

TimerCancelled

Points to a caller-supplied variable, which this function sets to TRUE if the timer was queued and then cancelled, or to FALSE if the timer either was not set or has already fired.

Comments

All NdisM..Timer functions operate on an opaque timer object, for which a NIC driver must supply resident storage. The MiniportInitialize function must call NdisMInitializeTimer with a caller-supplied pointer to this storage, thereby associating a driver-supplied MiniportTimer function with the timer object. MiniportInitialize must call NdisMInitializeTimer before the driver passes the Timer pointer to any other NdisM..Timer function.

Drivers of NICs that do not generate interrupts have a polling MiniportTimer function to monitor the NIC state for incoming receives and for send completions.

Calls to the NdisMSet..Timer functions insert the timer object in the system timer queue. Calls to NdisMCancelTimer dequeue the timer object if it is currently queued. Only one instantiation of a particular timer object can be queued at any given moment.

A call to NdisMCancelTimer while the timer object designated by Timer is queued removes the timer object from the queue, thereby cancelling the execution of the associated MiniportTimer function.

A subsequent call to NdisMSetTimer or NdisMSetPeriodicTimer requeues the timer object so the MiniportTimer function again will be run when the given interval expires.

A call to NdisMCancelTimer can occur just after a timer has fired but before the associated MiniportTimer function is run. Usually, a MiniportTimer function sets a state variable immediately on entry to indicate that it is running. When another miniport function calls NdisMCancelTimer, it can check such a TimerCancelled variable on return from this call to determine whether its call to NdisMCancelTimer also cancelled execution of the MiniportTimer function.

A call to NdisMCancelTimer while the MiniportTimer function is running has no effect on the execution of MiniportTimer. It continues to run until it returns control.

Callers of NdisMCancelTimer run at IRQL <= DISPATCH_LEVEL.