WdfTimerStart 函数 (wdftimer.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfTimerStart 方法启动计时器的时钟。

语法

BOOLEAN WdfTimerStart(
  [in] WDFTIMER Timer,
  [in] LONGLONG DueTime
);

参数

[in] Timer

通过调用 WdfTimerCreate 获取的框架计时器对象的句柄。

[in] DueTime

一个时间段，以系统时间单位 (100 纳秒的间隔) 。 当指定的时间段过去时，框架会调用驱动程序的 EvtTimerFunc 回调函数。 时间段值可以是负值或正值，如下所示：

  • 如果值为负值，则时间段相对于当前系统时间。
  • 如果值为正值，则时间段指定一个绝对时间 (实际相对于 1601 年 1 月 1 日) 。

警告

如果将 WDF_TIMER_CONFIG 的 UseHighResolutionTimer 成员设置为 WdfTrue，则必须调用 WdfTimerStart，并将 DueTime 参数设置为负值。 否则，调用会导致系统崩溃。

相对时间不受在指定时间段内可能发生的系统时间的任何更改的影响。 绝对时间确实反映了系统时间更改。

框架提供 时间转换函数 ，用于将时间值转换为系统时间单位。

返回值

如果计时器对象位于系统的计时器队列中，则 WdfTimerStart 返回 TRUE。 否则，此方法返回 FALSE。 有关更多信息，请参见下面的“备注”部分。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

驱动程序必须始终调用 WdfTimerStart ，以在创建计时器后启动计时器，而不管计时器是否为定期计时器。

驱动程序调用 WdfTimerStart 后，框架会在为 DueTime 参数指定的时间过后调用驱动程序的 EvtTimerFunc 回调函数。 第一次调用后，每当驱动程序WDF_TIMER_CONFIG结构的Period 成员指定的时间段过后，框架都会调用回调函数。

计时器的过期最终取决于系统时钟的粒度。 为 DueTime 指定的值保证框架在给定 DueTime 上或之后调用驱动程序的 EvtTimerFunc 回调函数。 但是，无论为 DueTime 指定的值如何，WdfTimerStart 都不能覆盖系统时钟的粒度。

当驱动程序调用 WdfTimerStart 时，其计时器对象将添加到系统的计时器对象队列中。 如果计时器不是定期计时器，系统会在计时器的“到期时间”过后从队列中删除计时器对象。 如果计时器是定期计时器，则计时器对象将保留在队列中，直到驱动程序调用 WdfTimerStop。

驱动程序可能会从其 EvtTimerFunc 回调函数调用 WdfTimerStart，以便在非定期计时器过期后重新启动它。

如果驱动程序以前已调用 WdfTimerStart，并且计时器对象仍位于系统的队列中，则 WdfTimerStart 返回 TRUE，因为该时间段尚未经过 (或因为它是定期计时器) 。 在 WdfTimerStart 返回 TRUE 之前，操作系统会将时间段重置为驱动程序在新调用 WdfTimerStart 中指定的值。 框架仅在新时间段过后调用 EvtTimerFunc 回调函数。

若要停止计时器的时钟，驱动程序可以调用 WdfTimerStop。

有关框架计时器对象的详细信息，请参阅 使用计时器。

示例

下面的代码示例启动计时器。 框架将在 10 毫秒后调用计时器的 EvtTimerFunc 回调函数。

BOOLEAN inTimerQueue;

inTimerQueue = WdfTimerStart(
                             timerHandle,
                             WDF_REL_TIMEOUT_IN_MS(10)
                             );

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdftimer.h (包括 Wdf.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

EvtTimerFunc

WDF_TIMER_CONFIG

WdfTimerCreate

WdfTimerStop