Edit

NDIS_TIMER_FUNCTION callback function (ndis.h)

  • Article

The NdisTimerFunction callback function is called by NDIS after a driver sets a one-shot or periodic timer when a timer fires.

Note  You must declare the function by using the NDIS_TIMER_FUNCTION type. For more information, see the following Examples section.
 

Syntax

NDIS_TIMER_FUNCTION NdisTimerFunction;

void NdisTimerFunction(
  [in] PVOID SystemSpecific1,
  [in] PVOID FunctionContext,
  [in] PVOID SystemSpecific2,
  [in] PVOID SystemSpecific3
)
{...}

Parameters

[in] SystemSpecific1

A pointer to a system-specific value that is reserved for system use.

[in] FunctionContext

A pointer to a driver-supplied context area that the driver passed to the NdisSetTimerObject function. If the FunctionContext parameter of NdisSetTimerObject was NULL, NDIS uses the default value that the driver specified in the NDIS_TIMER_CHARACTERISTICS structure. The driver passed the structure to the NdisAllocateTimerObject function to initialize the associated timer object.

[in] SystemSpecific2

A pointer to a system-specific value that is reserved for system use.

[in] SystemSpecific3

A pointer to a system-specific value that is reserved for system use.

Return value

None

Remarks

Any NDIS driver can have one or more NdisTimerFunction callback functions. Each such NdisTimerFunction callback must be associated with a different driver-allocated and initialized timer object.

The driver initializes a driver-allocated timer object by calling the NdisAllocateTimerObject function.

A subsequent call to the NdisSetTimerObject function causes the NdisTimerFunction callback that is associated with the timer object to be run after a specified interval or periodically.

To cancel calls to NdisTimerFunction, call the NdisCancelTimerObject function. NDIS might still call NdisTimerFunction if the timeout has already expired before the call to NdisCancelTimerObject.

If a NdisTimerFunction callback shares resources with other driver functions, the driver should synchronize access to those resources with a spin lock.

Examples

To define a NdisTimerFunction function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a NdisTimerFunction function that is named "MyTimerCallback", use the NDIS_TIMER_FUNCTION type as shown in this code example:

NDIS_TIMER_FUNCTION MyTimerCallback;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyTimerCallback(
    PVOID  SystemSpecific1,
    PVOID  FunctionContext,
    PVOID  SystemSpecific2,
    PVOID  SystemSpecific3
    )
  {...}

The NDIS_TIMER_FUNCTION function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the NDIS_TIMER_FUNCTION function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement Value
Minimum supported client Supported in NDIS 6.0 and later.
Target Platform Windows
Header ndis.h (include Ndis.h)
IRQL DISPATCH_LEVEL

See also

Initializing NDIS Timers

NDIS_TIMER_CHARACTERISTICS

NdisAllocateTimerObject

NdisCancelTimerObject

NdisSetTimerObject

Servicing Timers

Setting and Clearing Timers