NdisSetTimerObject function (ndis.h)

Article
04/18/2022

The NdisSetTimerObject function sets a timer object to fire after a specified interval or periodically.

Syntax

BOOLEAN NdisSetTimerObject(
  [in]           NDIS_HANDLE   TimerObject,
  [in]           LARGE_INTEGER DueTime,
  [in, optional] LONG          MillisecondsPeriod,
  [in, optional] PVOID         FunctionContext
);

Parameters

[in] TimerObject

A handle to a timer object that NDIS provides when a driver calls the NdisAllocateTimerObject function.

[in] DueTime

The absolute or relative time at which the timer is to expire. If the value of the DueTime parameter is negative, the expiration time is relative to the current system time. Otherwise, the expiration time is absolute. The expiration time is expressed in system time units (100-nanosecond intervals). Absolute expiration times track any changes in the system time; relative expiration times are not affected by system time changes.

[in, optional] MillisecondsPeriod

The periodic time interval, in milliseconds, that elapses between each time the timer fires and the next call to the NetTimerCallback function, unless the timer is canceled. The value of this parameter must be less than or equal to MAXLONG.

[in, optional] FunctionContext

A pointer to a caller-supplied context area that NDIS passes to the associated NetTimerCallback function when a timer fires. If this parameter is NULL, NDIS uses the default value that is specified in the NDIS_TIMER_CHARACTERISTICS structure.

Return value

NdisSetTimerObject returns TRUE if the timer object was already in the system timer queue; otherwise, it returns FALSE.

Remarks

After a driver calls NdisSetTimerObject, the timer object is queued until the interval that is specified in the DueTime parameter expires. After the interval expires, the timer object is dequeued and the caller-supplied NetTimerCallback function is run once at IRQL = DISPATCH_LEVEL as soon as a processor becomes available.

If a nonzero value is specified in the MillisecondsPeriod parameter, the timer object is queued again until the interval that is specified in MillisecondsPeriod expires. After this interval expires, the timer object is requeued and the caller-supplied NetTimerCallback function is run once at IRQL = DISPATCH_LEVEL as soon as a processor becomes available.

Note Starting with Windows 7, you can reduce power consumption by calling NdisSetCoalescableTimerObject instead of NdisSetTimerObject if exact timer precision is not required.

For more information about timer behavior, see KeSetTimerEx.

To cancel a timer, call the NdisCancelTimerObject function.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Universal
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	Irql_Timer_Function(ndis), PeriodicTimer(ndis)