EXT_CALLBACK callback function (wdm.h)

Article
02/28/2023

An ExTimerCallback callback routine runs after an EX_TIMER timer object's time interval expires.

Syntax

EXT_CALLBACK ExtCallback;

void ExtCallback(
  [in] PEX_TIMER Timer,
  [in] PVOID Context
)
{...}

Parameters

[in] Timer

A pointer to an EX_TIMER structure. This structure is a timer object that was previously allocated by the ExAllocateTimer routine.

[in] Context

The context value that your driver previously supplied as the CallbackContext parameter of the ExAllocateTimer routine.

Return value

None

Remarks

As an option, your driver can supply a pointer to an ExTimerCallback routine in the Callback parameter that your driver passes to the ExAllocateTimer routine. After the timer expires, the operating system calls the ExTimerCallback routine.

To start a timer operation, the driver passes the timer object as an input parameter to the ExSetTimer routine. After the timer expires, the operating system schedules the ExTimerCallback routine to run.

A timer object is a waitable object. A driver thread can call a routine such as KeWaitForSingleObject or KeWaitForMultipleObjects to wait for the timer to expire. When the timer expires, the operating system signals the timer object.

A timer might be canceled before it expires. The driver can call the ExCancelTimer routine to explicitly cancel a timer. If the driver calls the ExSetTimer routine to start a new timer on a timer object before a previously set timer on this object expires, this call implicitly cancels the previous timer and then starts the new timer.

An ExTimerCallback routine can call a routine such as ExSetTimer or ExDeleteTimer. If an ExTimerCallback routine calls ExDeleteTimer, the Wait parameter supplied in this call must be FALSE. For more information, see Deleting a System-Allocated Timer Object.

In a multiprocessor system, ExTimerCallback callbacks for two successive expirations of a periodic timer might simultaneously run on two different processors.

For more information, see ExXxxTimer Routines and EX_TIMER Objects.

Examples

To define an ExTimerCallback callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function type 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 an ExTimerCallback callback routine that is named MyExTimerCallback, use the EXT_CALLBACK function type, as shown in this code example:

EXT_CALLBACK  MyExTimerCallback;

Then, implement your callback routine as follows:

_Use_decl_annotations_
VOID
  MyExTimerCallback(
    PEX_TIMER  Timer,
    PVOID  Context
    )
  {...}

The EXT_CALLBACK function type is defined in the Wdm.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 EXT_CALLBACK function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions Using Function Role Types for WDM Drivers. For more information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.1.
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Called at DISPATCH_LEVEL.

Share via